Delete fr/bonus-unit2/.ipynb_checkpoints
Browse files
fr/bonus-unit2/.ipynb_checkpoints/monitoring-and-evaluating-agents-checkpoint.ipynb
DELETED
|
@@ -1,657 +0,0 @@
|
|
| 1 |
-
{
|
| 2 |
-
"cells": [
|
| 3 |
-
{
|
| 4 |
-
"cell_type": "markdown",
|
| 5 |
-
"metadata": {},
|
| 6 |
-
"source": [
|
| 7 |
-
"# Unité Bonus 2 : Observabilité et évaluation des agents\n",
|
| 8 |
-
"\n",
|
| 9 |
-
"Dans ce tutoriel, nous allons apprendre à **surveiller les étapes internes (traces) de notre agent** et **évaluer sa performance** en utilisant des outils d'observabilité open-source.\n",
|
| 10 |
-
"\n",
|
| 11 |
-
"La capacité d'observer et d'évaluer le comportement d'un agent est essentielle pour :\n",
|
| 12 |
-
"- Déboguer les problèmes lorsque les tâches échouent ou produisent des résultats sous-optimaux\n",
|
| 13 |
-
"- Contrôler les coûts et les performances en temps réel\n",
|
| 14 |
-
"- Améliorer la fiabilité et la sécurité grâce à un retour d'information continu\n",
|
| 15 |
-
"\n",
|
| 16 |
-
"Ce *notebook* fait partie du [Cours sur les agents d'Hugging Face](https://huggingface.co/learn/agents-course/fr)."
|
| 17 |
-
]
|
| 18 |
-
},
|
| 19 |
-
{
|
| 20 |
-
"cell_type": "markdown",
|
| 21 |
-
"metadata": {},
|
| 22 |
-
"source": [
|
| 23 |
-
"## Prérequis de l'exercice 🏗️\n",
|
| 24 |
-
"\n",
|
| 25 |
-
"Avant d'exécuter ce *notebook*, assurez-vous d'avoir :\n",
|
| 26 |
-
"\n",
|
| 27 |
-
"🔲 📚 **Etudier la section [Introduction aux agents](https://huggingface.co/learn/agents-course/fr/unit1/introduction)**\n",
|
| 28 |
-
"\n",
|
| 29 |
-
"🔲 📚 **Etudier la section [le *framework* smolagents](https://huggingface.co/learn/agents-course/fr/unit2/smolagents/introduction)**"
|
| 30 |
-
]
|
| 31 |
-
},
|
| 32 |
-
{
|
| 33 |
-
"cell_type": "markdown",
|
| 34 |
-
"metadata": {},
|
| 35 |
-
"source": [
|
| 36 |
-
"## Étape 0 : Installer les bibliothèques nécessaires\n",
|
| 37 |
-
"\n",
|
| 38 |
-
"Nous aurons besoin de quelques bibliothèques qui nous permettront d'exécuter, de contrôler et d'évaluer nos agents :"
|
| 39 |
-
]
|
| 40 |
-
},
|
| 41 |
-
{
|
| 42 |
-
"cell_type": "code",
|
| 43 |
-
"execution_count": null,
|
| 44 |
-
"metadata": {},
|
| 45 |
-
"outputs": [],
|
| 46 |
-
"source": [
|
| 47 |
-
"%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents datasets 'smolagents[gradio]' gradio --upgrade"
|
| 48 |
-
]
|
| 49 |
-
},
|
| 50 |
-
{
|
| 51 |
-
"cell_type": "markdown",
|
| 52 |
-
"metadata": {},
|
| 53 |
-
"source": [
|
| 54 |
-
"## Étape 1 : Instrumenter votre agent\n",
|
| 55 |
-
"\n",
|
| 56 |
-
"Dans ce *notebook*, nous utiliserons [Langfuse](https://langfuse.com/) comme outil d'observabilité, mais vous pouvez utiliser **n'importe quel autre service compatible avec OpenTelemetry**. Le code ci-dessous montre comment définir les variables d'environnement pour Langfuse (ou n'importe quel *endpoint OTel*) et comment instrumenter votre smolagent.\n",
|
| 57 |
-
"\n",
|
| 58 |
-
"**Note :** Si vous utilisez LlamaIndex ou LangGraph, vous pouvez trouver de la documentation sur leur instrumentation [ici](https://langfuse.com/docs/integrations/llama-index/workflows) et [ici](https://langfuse.com/docs/integrations/langchain/example-python-langgraph)."
|
| 59 |
-
]
|
| 60 |
-
},
|
| 61 |
-
{
|
| 62 |
-
"cell_type": "code",
|
| 63 |
-
"execution_count": 1,
|
| 64 |
-
"metadata": {},
|
| 65 |
-
"outputs": [],
|
| 66 |
-
"source": [
|
| 67 |
-
"import os\n",
|
| 68 |
-
"\n",
|
| 69 |
-
"# Obtenez les clés de votre projet à partir de la page des paramètres du projet : https://cloud.langfuse.com\n",
|
| 70 |
-
"os.environ[\"LANGFUSE_PUBLIC_KEY\"] = \"pk-lf-...\" \n",
|
| 71 |
-
"os.environ[\"LANGFUSE_SECRET_KEY\"] = \"sk-lf-...\" \n",
|
| 72 |
-
"os.environ[\"LANGFUSE_HOST\"] = \"https://cloud.langfuse.com\" # 🇪🇺 région EU\n",
|
| 73 |
-
"# os.environ[\"LANGFUSE_HOST\"] = \"https://us.cloud.langfuse.com\" # 🇺🇸 région US\n",
|
| 74 |
-
"\n",
|
| 75 |
-
"# Définissez vos tokens/secrets Hugging Face comme variable d'environnement\n",
|
| 76 |
-
"os.environ[\"HF_TOKEN\"] = \"hf_...\" "
|
| 77 |
-
]
|
| 78 |
-
},
|
| 79 |
-
{
|
| 80 |
-
"cell_type": "markdown",
|
| 81 |
-
"metadata": {},
|
| 82 |
-
"source": [
|
| 83 |
-
"Les variables d'environnement étant définies, nous pouvons maintenant initialiser le client de Langfuse `get_client()` initialise le client Langfuse en utilisant les informations d'identification fournies dans les variables d'environnement."
|
| 84 |
-
]
|
| 85 |
-
},
|
| 86 |
-
{
|
| 87 |
-
"cell_type": "code",
|
| 88 |
-
"execution_count": 12,
|
| 89 |
-
"metadata": {},
|
| 90 |
-
"outputs": [
|
| 91 |
-
{
|
| 92 |
-
"name": "stdout",
|
| 93 |
-
"output_type": "stream",
|
| 94 |
-
"text": [
|
| 95 |
-
"Langfuse client is authenticated and ready!\n"
|
| 96 |
-
]
|
| 97 |
-
}
|
| 98 |
-
],
|
| 99 |
-
"source": [
|
| 100 |
-
"from langfuse import get_client\n",
|
| 101 |
-
" \n",
|
| 102 |
-
"langfuse = get_client()\n",
|
| 103 |
-
" \n",
|
| 104 |
-
"# Verify connection\n",
|
| 105 |
-
"if langfuse.auth_check():\n",
|
| 106 |
-
" print(\"Langfuse client is authenticated and ready!\")\n",
|
| 107 |
-
"else:\n",
|
| 108 |
-
" print(\"Authentication failed. Please check your credentials and host.\")"
|
| 109 |
-
]
|
| 110 |
-
},
|
| 111 |
-
{
|
| 112 |
-
"cell_type": "code",
|
| 113 |
-
"execution_count": 13,
|
| 114 |
-
"metadata": {},
|
| 115 |
-
"outputs": [
|
| 116 |
-
{
|
| 117 |
-
"name": "stderr",
|
| 118 |
-
"output_type": "stream",
|
| 119 |
-
"text": [
|
| 120 |
-
"Attempting to instrument while already instrumented\n"
|
| 121 |
-
]
|
| 122 |
-
}
|
| 123 |
-
],
|
| 124 |
-
"source": [
|
| 125 |
-
"from openinference.instrumentation.smolagents import SmolagentsInstrumentor\n",
|
| 126 |
-
" \n",
|
| 127 |
-
"SmolagentsInstrumentor().instrument()"
|
| 128 |
-
]
|
| 129 |
-
},
|
| 130 |
-
{
|
| 131 |
-
"cell_type": "markdown",
|
| 132 |
-
"metadata": {},
|
| 133 |
-
"source": [
|
| 134 |
-
"## Étape 2 : Testez votre instrumentation\n",
|
| 135 |
-
"\n",
|
| 136 |
-
"Voici un simple CodeAgent de smolagents qui calcule `1+1`. Nous l'exécutons pour confirmer que l'instrumentation fonctionne correctement. Si tout est configuré correctement, vous verrez des logs/spans dans votre tableau de bord d'observabilité."
|
| 137 |
-
]
|
| 138 |
-
},
|
| 139 |
-
{
|
| 140 |
-
"cell_type": "code",
|
| 141 |
-
"execution_count": null,
|
| 142 |
-
"metadata": {},
|
| 143 |
-
"outputs": [],
|
| 144 |
-
"source": [
|
| 145 |
-
"from smolagents import InferenceClientModel, CodeAgent\n",
|
| 146 |
-
"\n",
|
| 147 |
-
"# Créer un agent basique pour tester l'instrumentation\n",
|
| 148 |
-
"agent = CodeAgent(\n",
|
| 149 |
-
" tools=[],\n",
|
| 150 |
-
" model=InferenceClientModel()\n",
|
| 151 |
-
")\n",
|
| 152 |
-
"\n",
|
| 153 |
-
"agent.run(\"1+1=\")"
|
| 154 |
-
]
|
| 155 |
-
},
|
| 156 |
-
{
|
| 157 |
-
"cell_type": "markdown",
|
| 158 |
-
"metadata": {},
|
| 159 |
-
"source": [
|
| 160 |
-
"Consultez votre [Langfuse Traces Dashboard](https://cloud.langfuse.com/traces) (ou l'outil d'observabilité de votre choix) pour confirmer que les portées et les logs ont été enregistrés.\n",
|
| 161 |
-
"\n",
|
| 162 |
-
"Exemple de capture d'écran de Langfuse :\n",
|
| 163 |
-
"\n",
|
| 164 |
-
"\n",
|
| 165 |
-
"\n",
|
| 166 |
-
"_[Lien vers la trace](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/1b94d6888258e0998329cdb72a371155?timestamp=2025-03-10T11%3A59%3A41.743Z)_"
|
| 167 |
-
]
|
| 168 |
-
},
|
| 169 |
-
{
|
| 170 |
-
"cell_type": "markdown",
|
| 171 |
-
"metadata": {},
|
| 172 |
-
"source": [
|
| 173 |
-
"## Étape 3 : Observer et évaluer un agent plus complexe\n",
|
| 174 |
-
"\n",
|
| 175 |
-
"Maintenant que vous avez confirmé que votre instrumentation fonctionne, essayons une requête plus complexe afin de voir comment les mesures avancées (utilisation des *tokens*, latence, coûts, etc.) sont suivies."
|
| 176 |
-
]
|
| 177 |
-
},
|
| 178 |
-
{
|
| 179 |
-
"cell_type": "code",
|
| 180 |
-
"execution_count": null,
|
| 181 |
-
"metadata": {},
|
| 182 |
-
"outputs": [],
|
| 183 |
-
"source": [
|
| 184 |
-
"from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)\n",
|
| 185 |
-
"\n",
|
| 186 |
-
"search_tool = DuckDuckGoSearchTool()\n",
|
| 187 |
-
"agent = CodeAgent(tools=[search_tool], model=InferenceClientModel())\n",
|
| 188 |
-
"\n",
|
| 189 |
-
"agent.run(\"How many Rubik's Cubes could you fit inside the Notre Dame Cathedral?\")"
|
| 190 |
-
]
|
| 191 |
-
},
|
| 192 |
-
{
|
| 193 |
-
"cell_type": "markdown",
|
| 194 |
-
"metadata": {},
|
| 195 |
-
"source": [
|
| 196 |
-
"### Structure de la trace\n",
|
| 197 |
-
"\n",
|
| 198 |
-
"La plupart des outils d'observabilité enregistrent une **trace** qui contient des **spans**, qui représentent chaque étape de la logique de votre agent. Ici, la trace contient l'exécution globale de l'agent et les sous-périodes pour :\n",
|
| 199 |
-
"- les appels à l'outil (DuckDuckGoSearchTool)\n",
|
| 200 |
-
"- Les appels LLM (InferenceClientModel)\n",
|
| 201 |
-
"\n",
|
| 202 |
-
"Vous pouvez les inspecter pour voir précisément où le temps est passé, combien de *tokens* sont utilisés, etc. :\n",
|
| 203 |
-
"\n",
|
| 204 |
-
"\n",
|
| 205 |
-
"\n",
|
| 206 |
-
"_[Lien vers la trace](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/1ac33b89ffd5e75d4265b62900c348ed?timestamp=2025-03-07T13%3A45%3A09.149Z&display=preview)_"
|
| 207 |
-
]
|
| 208 |
-
},
|
| 209 |
-
{
|
| 210 |
-
"cell_type": "markdown",
|
| 211 |
-
"metadata": {},
|
| 212 |
-
"source": [
|
| 213 |
-
"## Évaluation en ligne\n",
|
| 214 |
-
"\n",
|
| 215 |
-
"Dans la section précédente, nous avons appris la différence entre l'évaluation en ligne et hors ligne. Nous allons maintenant voir comment surveiller votre agent en production et l'évaluer en direct.\n",
|
| 216 |
-
"\n",
|
| 217 |
-
"### Mesures courantes à suivre en production\n",
|
| 218 |
-
"\n",
|
| 219 |
-
"1. **Coûts** - L'instrumentation smolagents capture l'utilisation des *tokens*, que vous pouvez transformer en coûts approximatifs en assignant un prix par *token*.\n",
|
| 220 |
-
"2. **Latence** - Observez le temps nécessaire à la réalisation de chaque étape ou de l'ensemble de l'exécution.\n",
|
| 221 |
-
"3. **Retour utilisateur** - Les utilisateurs peuvent fournir un retour direct (pouce vers le haut/vers le bas) pour aider à affiner ou à corriger l'agent.\n",
|
| 222 |
-
"4. ***LLM-as-a-Judge*** - Utilisez un autre LLM pour évaluer les résultats de votre agent en quasi temps réel (par exemple, vérification de la toxicité ou de l'exactitude des résultats).\n",
|
| 223 |
-
"\n",
|
| 224 |
-
"Ci-dessous, nous montrons des exemples de ces mesures."
|
| 225 |
-
]
|
| 226 |
-
},
|
| 227 |
-
{
|
| 228 |
-
"cell_type": "markdown",
|
| 229 |
-
"metadata": {},
|
| 230 |
-
"source": [
|
| 231 |
-
"#### 1. Coûts\n",
|
| 232 |
-
"\n",
|
| 233 |
-
"Vous trouverez ci-dessous une capture d'écran montrant l'utilisation des appels `Qwen2.5-Coder-32B-Instruct`. Ceci est utile pour voir les étapes coûteuses et optimiser votre agent.\n",
|
| 234 |
-
"\n",
|
| 235 |
-
"\n",
|
| 236 |
-
"\n",
|
| 237 |
-
"_[Lien vers la trace](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/1ac33b89ffd5e75d4265b62900c348ed?timestamp=2025-03-07T13%3A45%3A09.149Z&display=preview)_"
|
| 238 |
-
]
|
| 239 |
-
},
|
| 240 |
-
{
|
| 241 |
-
"cell_type": "markdown",
|
| 242 |
-
"metadata": {},
|
| 243 |
-
"source": [
|
| 244 |
-
"#### 2. Temps de latence\n",
|
| 245 |
-
"\n",
|
| 246 |
-
"Nous pouvons également voir combien de temps a duré chaque étape. Dans l'exemple ci-dessous, l'ensemble de la conversation a duré 32 secondes, que vous pouvez répartir par étape. Cela vous permet d'identifier les goulets d'étranglement et d'optimiser votre agent.\n",
|
| 247 |
-
"\n",
|
| 248 |
-
"\n",
|
| 249 |
-
"\n",
|
| 250 |
-
"_[Lien vers la trace](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/1ac33b89ffd5e75d4265b62900c348ed?timestamp=2025-03-07T13%3A45%3A09.149Z&display=preview)_"
|
| 251 |
-
]
|
| 252 |
-
},
|
| 253 |
-
{
|
| 254 |
-
"cell_type": "markdown",
|
| 255 |
-
"metadata": {},
|
| 256 |
-
"source": [
|
| 257 |
-
"#### 3. Attributs supplémentaires\n",
|
| 258 |
-
"\n",
|
| 259 |
-
"Vous pouvez également passer des attributs supplémentaires à vos spans. Ceux-ci peuvent inclure `user_id`, `tags`, `session_id`, et des métadonnées personnalisées. Enrichir les traces avec ces détails est important pour l'analyse, le débogage et la surveillance du comportement de votre application à travers différents utilisateurs ou sessions."
|
| 260 |
-
]
|
| 261 |
-
},
|
| 262 |
-
{
|
| 263 |
-
"cell_type": "code",
|
| 264 |
-
"execution_count": null,
|
| 265 |
-
"metadata": {},
|
| 266 |
-
"outputs": [],
|
| 267 |
-
"source": [
|
| 268 |
-
"from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)\n",
|
| 269 |
-
"\n",
|
| 270 |
-
"search_tool = DuckDuckGoSearchTool()\n",
|
| 271 |
-
"agent = CodeAgent(\n",
|
| 272 |
-
" tools=[search_tool],\n",
|
| 273 |
-
" model=InferenceClientModel()\n",
|
| 274 |
-
")\n",
|
| 275 |
-
"\n",
|
| 276 |
-
"with langfuse.start_as_current_span(\n",
|
| 277 |
-
" name=\"Smolagent-Trace\",\n",
|
| 278 |
-
" ) as span:\n",
|
| 279 |
-
" \n",
|
| 280 |
-
" # Lancez votre candidature ici\n",
|
| 281 |
-
" response = agent.run(\"What is the capital of Germany?\")\n",
|
| 282 |
-
" \n",
|
| 283 |
-
" # Transmettre des attributs supplémentaires au span\n",
|
| 284 |
-
" span.update_trace(\n",
|
| 285 |
-
" input=\"What is the capital of Germany?\",\n",
|
| 286 |
-
" output=response,\n",
|
| 287 |
-
" user_id=\"smolagent-user-123\",\n",
|
| 288 |
-
" session_id=\"smolagent-session-123456789\",\n",
|
| 289 |
-
" tags=[\"city-question\", \"testing-agents\"],\n",
|
| 290 |
-
" metadata={\"email\": \"user@langfuse.com\"},\n",
|
| 291 |
-
" )\n",
|
| 292 |
-
" \n",
|
| 293 |
-
"langfuse.flush()"
|
| 294 |
-
]
|
| 295 |
-
},
|
| 296 |
-
{
|
| 297 |
-
"cell_type": "markdown",
|
| 298 |
-
"metadata": {},
|
| 299 |
-
"source": [
|
| 300 |
-
""
|
| 301 |
-
]
|
| 302 |
-
},
|
| 303 |
-
{
|
| 304 |
-
"cell_type": "markdown",
|
| 305 |
-
"metadata": {},
|
| 306 |
-
"source": [
|
| 307 |
-
"#### 4. Retour utilisateur\n",
|
| 308 |
-
"\n",
|
| 309 |
-
"Si votre agent est intégré dans une interface utilisateur, vous pouvez enregistrer les réactions directes de l'utilisateur (comme un pouce levé ou baissé dans une interface de discussion). Vous trouverez ci-dessous un exemple utilisant [Gradio](https://gradio.app/) pour intégrer un chat avec un mécanisme de retour d'information simple.\n",
|
| 310 |
-
"\n",
|
| 311 |
-
"Dans l'extrait de code ci-dessous, lorsqu'un utilisateur envoie un message de chat, nous capturons la trace dans Langfuse. Si l'utilisateur aime ou n'aime pas la dernière réponse, nous attribuons un score à la trace."
|
| 312 |
-
]
|
| 313 |
-
},
|
| 314 |
-
{
|
| 315 |
-
"cell_type": "code",
|
| 316 |
-
"execution_count": null,
|
| 317 |
-
"metadata": {},
|
| 318 |
-
"outputs": [],
|
| 319 |
-
"source": [
|
| 320 |
-
"import gradio as gr\n",
|
| 321 |
-
"from smolagents import (CodeAgent, InferenceClientModel)\n",
|
| 322 |
-
"from langfuse import get_client\n",
|
| 323 |
-
"\n",
|
| 324 |
-
"langfuse = get_client()\n",
|
| 325 |
-
"\n",
|
| 326 |
-
"model = InferenceClientModel()\n",
|
| 327 |
-
"agent = CodeAgent(tools=[], model=model, add_base_tools=True)\n",
|
| 328 |
-
"\n",
|
| 329 |
-
"trace_id = None\n",
|
| 330 |
-
"\n",
|
| 331 |
-
"def respond(prompt, history):\n",
|
| 332 |
-
" with langfuse.start_as_current_span(\n",
|
| 333 |
-
" name=\"Smolagent-Trace\"):\n",
|
| 334 |
-
" \n",
|
| 335 |
-
" # Exécuter l'application\n",
|
| 336 |
-
" output = agent.run(prompt)\n",
|
| 337 |
-
"\n",
|
| 338 |
-
" global trace_id\n",
|
| 339 |
-
" trace_id = langfuse.get_current_trace_id()\n",
|
| 340 |
-
"\n",
|
| 341 |
-
" history.append({\"role\": \"assistant\", \"content\": str(output)})\n",
|
| 342 |
-
" return history\n",
|
| 343 |
-
"\n",
|
| 344 |
-
"def handle_like(data: gr.LikeData):\n",
|
| 345 |
-
" # À titre de démonstration, nous attribuons aux retours utilisateurs une valeur de 1 (j'aime) ou de 0 (je n'aime pas)\n",
|
| 346 |
-
" if data.liked:\n",
|
| 347 |
-
" langfuse.create_score(\n",
|
| 348 |
-
" value=1,\n",
|
| 349 |
-
" name=\"user-feedback\",\n",
|
| 350 |
-
" trace_id=trace_id\n",
|
| 351 |
-
" )\n",
|
| 352 |
-
" else:\n",
|
| 353 |
-
" langfuse.create_score(\n",
|
| 354 |
-
" value=0,\n",
|
| 355 |
-
" name=\"user-feedback\",\n",
|
| 356 |
-
" trace_id=trace_id\n",
|
| 357 |
-
" )\n",
|
| 358 |
-
"\n",
|
| 359 |
-
"with gr.Blocks() as demo:\n",
|
| 360 |
-
" chatbot = gr.Chatbot(label=\"Chat\", type=\"messages\")\n",
|
| 361 |
-
" prompt_box = gr.Textbox(placeholder=\"Type your message...\", label=\"Your message\")\n",
|
| 362 |
-
"\n",
|
| 363 |
-
" # Lorsque l'utilisateur appuie sur “Enter”, nous exécutons 'respond'\n",
|
| 364 |
-
" prompt_box.submit(\n",
|
| 365 |
-
" fn=respond,\n",
|
| 366 |
-
" inputs=[prompt_box, chatbot],\n",
|
| 367 |
-
" outputs=chatbot\n",
|
| 368 |
-
" )\n",
|
| 369 |
-
"\n",
|
| 370 |
-
" # Lorsque l'utilisateur clique sur le bouton « J'aime » d'un message, nous exécutons 'handle_like'\n",
|
| 371 |
-
" chatbot.like(handle_like, None, None)\n",
|
| 372 |
-
"\n",
|
| 373 |
-
"demo.launch()\n"
|
| 374 |
-
]
|
| 375 |
-
},
|
| 376 |
-
{
|
| 377 |
-
"cell_type": "markdown",
|
| 378 |
-
"metadata": {},
|
| 379 |
-
"source": [
|
| 380 |
-
"Les commentaires des utilisateurs sont ensuite saisis dans votre outil d'observabilité :\n",
|
| 381 |
-
"\n",
|
| 382 |
-
""
|
| 383 |
-
]
|
| 384 |
-
},
|
| 385 |
-
{
|
| 386 |
-
"cell_type": "markdown",
|
| 387 |
-
"metadata": {},
|
| 388 |
-
"source": [
|
| 389 |
-
"#### 5. LLM-as-a-Judge\n",
|
| 390 |
-
"\n",
|
| 391 |
-
"LLM-as-a-Judge est une autre façon d'évaluer automatiquement les résultats de votre agent. Vous pouvez configurer l'appel d'un autre LLM pour évaluer l'exactitude, la toxicité, le style ou tout autre critère qui vous intéresse.\n",
|
| 392 |
-
"\n",
|
| 393 |
-
"**Fonctionnement** :\n",
|
| 394 |
-
"1. Vous définissez un **Modèle d'évaluation**, par exemple, « Vérifier si le texte est toxique ».\n",
|
| 395 |
-
"2. Chaque fois que votre agent génère un résultat, vous transmettez ce résultat à votre LLM juge avec le gabarit.\n",
|
| 396 |
-
"3. Le LLM juge répond avec un score ou une étiquette que vous enregistrez dans votre outil d'observabilité.\n",
|
| 397 |
-
"\n",
|
| 398 |
-
"Exemple de Langfuse :\n",
|
| 399 |
-
"\n",
|
| 400 |
-
"\n",
|
| 401 |
-
""
|
| 402 |
-
]
|
| 403 |
-
},
|
| 404 |
-
{
|
| 405 |
-
"cell_type": "code",
|
| 406 |
-
"execution_count": null,
|
| 407 |
-
"metadata": {},
|
| 408 |
-
"outputs": [],
|
| 409 |
-
"source": [
|
| 410 |
-
"# Exemple : Vérifier si la production de l'agent est toxique ou non\n",
|
| 411 |
-
"from smolagents import (CodeAgent, DuckDuckGoSearchTool, InferenceClientModel)\n",
|
| 412 |
-
"\n",
|
| 413 |
-
"search_tool = DuckDuckGoSearchTool()\n",
|
| 414 |
-
"agent = CodeAgent(tools=[search_tool], model=InferenceClientModel())\n",
|
| 415 |
-
"\n",
|
| 416 |
-
"agent.run(\"Can eating carrots improve your vision?\")"
|
| 417 |
-
]
|
| 418 |
-
},
|
| 419 |
-
{
|
| 420 |
-
"cell_type": "markdown",
|
| 421 |
-
"metadata": {},
|
| 422 |
-
"source": [
|
| 423 |
-
"Vous pouvez voir que la réponse de cet exemple est jugée « non toxique ».\n",
|
| 424 |
-
"\n",
|
| 425 |
-
""
|
| 426 |
-
]
|
| 427 |
-
},
|
| 428 |
-
{
|
| 429 |
-
"cell_type": "markdown",
|
| 430 |
-
"metadata": {},
|
| 431 |
-
"source": [
|
| 432 |
-
"#### 6. Aperçu des mesures d'observabilité\n",
|
| 433 |
-
"\n",
|
| 434 |
-
"Toutes ces mesures peuvent être visualisées ensemble dans des tableaux de bord. Cela vous permet de voir rapidement les performances de votre agent sur plusieurs sessions et vous aide à suivre les mesures de qualité au fil du temps.\n",
|
| 435 |
-
"\n",
|
| 436 |
-
""
|
| 437 |
-
]
|
| 438 |
-
},
|
| 439 |
-
{
|
| 440 |
-
"cell_type": "markdown",
|
| 441 |
-
"metadata": {},
|
| 442 |
-
"source": [
|
| 443 |
-
"## Évaluation hors ligne\n",
|
| 444 |
-
"\n",
|
| 445 |
-
"L'évaluation en ligne est essentielle pour obtenir un retour d'information en temps réel, mais vous avez également besoin d'une **évaluation hors ligne**, c'est-à-dire de vérifications systématiques avant ou pendant le développement. Cela permet de maintenir la qualité et la fiabilité avant de mettre les changements en production."
|
| 446 |
-
]
|
| 447 |
-
},
|
| 448 |
-
{
|
| 449 |
-
"cell_type": "markdown",
|
| 450 |
-
"metadata": {},
|
| 451 |
-
"source": [
|
| 452 |
-
"### Évaluation d'un jeu de données\n",
|
| 453 |
-
"\n",
|
| 454 |
-
"Lors d'une évaluation hors ligne, vous devez généralement\n",
|
| 455 |
-
"1. Disposer d'un jeu de données de référence (avec des paires de *prompts* et de résultats attendus)\n",
|
| 456 |
-
"2. Exécuter votre agent sur ce jeu de données\n",
|
| 457 |
-
"3. Comparer les résultats aux résultats attendus ou utiliser un mécanisme de notation supplémentaire.\n",
|
| 458 |
-
"\n",
|
| 459 |
-
"Ci-dessous, nous démontrons cette approche avec le jeu de données [GSM8K](https://huggingface.co/datasets/gsm8k), qui contient des questions et des solutions mathématiques."
|
| 460 |
-
]
|
| 461 |
-
},
|
| 462 |
-
{
|
| 463 |
-
"cell_type": "code",
|
| 464 |
-
"execution_count": null,
|
| 465 |
-
"metadata": {},
|
| 466 |
-
"outputs": [],
|
| 467 |
-
"source": [
|
| 468 |
-
"import pandas as pd\n",
|
| 469 |
-
"from datasets import load_dataset\n",
|
| 470 |
-
"\n",
|
| 471 |
-
"# Récupérer le GSM8K sur Hugging Face\n",
|
| 472 |
-
"dataset = load_dataset(\"openai/gsm8k\", 'main', split='train')\n",
|
| 473 |
-
"df = pd.DataFrame(dataset)\n",
|
| 474 |
-
"print(\"First few rows of GSM8K dataset:\")\n",
|
| 475 |
-
"print(df.head())"
|
| 476 |
-
]
|
| 477 |
-
},
|
| 478 |
-
{
|
| 479 |
-
"cell_type": "markdown",
|
| 480 |
-
"metadata": {},
|
| 481 |
-
"source": [
|
| 482 |
-
"Ensuite, nous créons un jeu de données dans Langfuse pour suivre les exécutions. Nous ajoutons ensuite chaque élément du jeu de données au système. \n",
|
| 483 |
-
"(Si vous n'utilisez pas Langfuse, vous pouvez simplement les stocker dans votre propre base de données ou dans un fichier local à des fins d'analyse)."
|
| 484 |
-
]
|
| 485 |
-
},
|
| 486 |
-
{
|
| 487 |
-
"cell_type": "code",
|
| 488 |
-
"execution_count": null,
|
| 489 |
-
"metadata": {},
|
| 490 |
-
"outputs": [],
|
| 491 |
-
"source": [
|
| 492 |
-
"from langfuse import get_client\n",
|
| 493 |
-
"langfuse = get_client()\n",
|
| 494 |
-
"\n",
|
| 495 |
-
"langfuse_dataset_name = \"gsm8k_dataset_huggingface\"\n",
|
| 496 |
-
"\n",
|
| 497 |
-
"# Créer un jeu de données dans Langfuse\n",
|
| 498 |
-
"langfuse.create_dataset(\n",
|
| 499 |
-
" name=langfuse_dataset_name,\n",
|
| 500 |
-
" description=\"GSM8K benchmark dataset uploaded from Huggingface\",\n",
|
| 501 |
-
" metadata={\n",
|
| 502 |
-
" \"date\": \"2025-03-10\", \n",
|
| 503 |
-
" \"type\": \"benchmark\"\n",
|
| 504 |
-
" }\n",
|
| 505 |
-
")"
|
| 506 |
-
]
|
| 507 |
-
},
|
| 508 |
-
{
|
| 509 |
-
"cell_type": "code",
|
| 510 |
-
"execution_count": null,
|
| 511 |
-
"metadata": {},
|
| 512 |
-
"outputs": [],
|
| 513 |
-
"source": [
|
| 514 |
-
"for idx, row in df.iterrows():\n",
|
| 515 |
-
" langfuse.create_dataset_item(\n",
|
| 516 |
-
" dataset_name=langfuse_dataset_name,\n",
|
| 517 |
-
" input={\"text\": row[\"question\"]},\n",
|
| 518 |
-
" expected_output={\"text\": row[\"answer\"]},\n",
|
| 519 |
-
" metadata={\"source_index\": idx}\n",
|
| 520 |
-
" )\n",
|
| 521 |
-
" if idx >= 9: # Ne télécharge que les 10 premiers éléments pour la démonstration\n",
|
| 522 |
-
" break"
|
| 523 |
-
]
|
| 524 |
-
},
|
| 525 |
-
{
|
| 526 |
-
"cell_type": "markdown",
|
| 527 |
-
"metadata": {},
|
| 528 |
-
"source": [
|
| 529 |
-
""
|
| 530 |
-
]
|
| 531 |
-
},
|
| 532 |
-
{
|
| 533 |
-
"cell_type": "markdown",
|
| 534 |
-
"metadata": {},
|
| 535 |
-
"source": [
|
| 536 |
-
"#### Exécution de l'agent sur le jeu de données\n",
|
| 537 |
-
"\n",
|
| 538 |
-
"Nous définissons une fonction d'aide `run_smolagent()` qui :\n",
|
| 539 |
-
"1. Démarre un span Langfuse\n",
|
| 540 |
-
"2. Exécute notre agent sur le *prompt*\n",
|
| 541 |
-
"3. Enregistre l'ID de la trace dans Langfuse\n",
|
| 542 |
-
"\n",
|
| 543 |
-
"Ensuite, nous parcourons en boucle chaque élément de l'ensemble de données, nous exécutons l'agent et nous lions la trace à l'élément de l'ensemble de données. Nous pouvons également joindre une note d'évaluation rapide si vous le souhaitez."
|
| 544 |
-
]
|
| 545 |
-
},
|
| 546 |
-
{
|
| 547 |
-
"cell_type": "code",
|
| 548 |
-
"execution_count": null,
|
| 549 |
-
"metadata": {},
|
| 550 |
-
"outputs": [],
|
| 551 |
-
"source": [
|
| 552 |
-
"from opentelemetry.trace import format_trace_id\n",
|
| 553 |
-
"from smolagents import (CodeAgent, InferenceClientModel, LiteLLMModel)\n",
|
| 554 |
-
"from langfuse import get_client\n",
|
| 555 |
-
" \n",
|
| 556 |
-
"langfuse = get_client()\n",
|
| 557 |
-
"\n",
|
| 558 |
-
"\n",
|
| 559 |
-
"# Exemple : utilisation de InferenceClientModel ou LiteLLMModel pour accéder aux modèles openai, anthropic, gemini, etc. :\n",
|
| 560 |
-
"model = InferenceClientModel()\n",
|
| 561 |
-
"\n",
|
| 562 |
-
"agent = CodeAgent(\n",
|
| 563 |
-
" tools=[],\n",
|
| 564 |
-
" model=model,\n",
|
| 565 |
-
" add_base_tools=True\n",
|
| 566 |
-
")\n",
|
| 567 |
-
"\n",
|
| 568 |
-
"dataset_name = \"gsm8k_dataset_huggingface\"\n",
|
| 569 |
-
"current_run_name = \"smolagent-notebook-run-01\" # Identifie ce cycle d'évaluation spécifique\n",
|
| 570 |
-
" \n",
|
| 571 |
-
"# Supposons que « run_smolagent » soit la fonction de l'application instrumentée\n",
|
| 572 |
-
"def run_smolagent(question):\n",
|
| 573 |
-
" with langfuse.start_as_current_generation(name=\"qna-llm-call\") as generation:\n",
|
| 574 |
-
" # Simuler un appel LLM\n",
|
| 575 |
-
" result = agent.run(question)\n",
|
| 576 |
-
" \n",
|
| 577 |
-
" # Mise à jour de la trace avec l'entrée et la sortie\n",
|
| 578 |
-
" generation.update_trace(\n",
|
| 579 |
-
" input= question,\n",
|
| 580 |
-
" output=result,\n",
|
| 581 |
-
" )\n",
|
| 582 |
-
" \n",
|
| 583 |
-
" return result\n",
|
| 584 |
-
" \n",
|
| 585 |
-
"dataset = langfuse.get_dataset(name=dataset_name) # Récupérez votre jeu de données pré-rempli\n",
|
| 586 |
-
" \n",
|
| 587 |
-
"for item in dataset.items:\n",
|
| 588 |
-
" \n",
|
| 589 |
-
" # Utiliser le gestionnaire de contexte item.run()\n",
|
| 590 |
-
" with item.run(\n",
|
| 591 |
-
" run_name=current_run_name,\n",
|
| 592 |
-
" run_metadata={\"model_provider\": \"Hugging Face\", \"temperature_setting\": 0.7},\n",
|
| 593 |
-
" run_description=\"Evaluation run for GSM8K dataset\"\n",
|
| 594 |
-
" ) as root_span: # root_span est le span racine de la nouvelle trace pour cet élément et l'exécution.\n",
|
| 595 |
-
" # Toutes les opérations langfuse subséquentes à l'intérieur de ce bloc font partie de cette trace.\n",
|
| 596 |
-
" \n",
|
| 597 |
-
" # Appelez votre logique d'application\n",
|
| 598 |
-
" generated_answer = run_smolagent(question=item.input[\"text\"])\n",
|
| 599 |
-
" \n",
|
| 600 |
-
" print(item.input)"
|
| 601 |
-
]
|
| 602 |
-
},
|
| 603 |
-
{
|
| 604 |
-
"cell_type": "markdown",
|
| 605 |
-
"metadata": {},
|
| 606 |
-
"source": [
|
| 607 |
-
"Vous pouvez répéter ce processus avec différents :\n",
|
| 608 |
-
"- Modèles (OpenAI GPT, LLM local, etc.)\n",
|
| 609 |
-
"- Outils (recherche ou pas recherche)\n",
|
| 610 |
-
"- Prompts (différents messages du système)\n",
|
| 611 |
-
"\n",
|
| 612 |
-
"Ensuite, comparez-les côte à côte dans votre outil d'observabilité :\n",
|
| 613 |
-
"\n",
|
| 614 |
-
"\n",
|
| 615 |
-
"\n"
|
| 616 |
-
]
|
| 617 |
-
},
|
| 618 |
-
{
|
| 619 |
-
"cell_type": "markdown",
|
| 620 |
-
"metadata": {},
|
| 621 |
-
"source": [
|
| 622 |
-
"## Réflexions finales\n",
|
| 623 |
-
"\n",
|
| 624 |
-
"Dans ce *notebook*, nous avons vu comment :\n",
|
| 625 |
-
"1. **Mettre en place l'observabilité** en utilisant les exportateurs smolagents + OpenTelemetry\n",
|
| 626 |
-
"2. **Vérifier l'instrumentation** en lançant un agent simple\n",
|
| 627 |
-
"3. **Capturez des métriques détaillées** (coût, latence, etc.) à l'aide d'outils d'observabilité\n",
|
| 628 |
-
"4. **Recueillir les commentaires des utilisateurs** via une interface Gradio\n",
|
| 629 |
-
"5. **Utiliser un LLM-as-a-Judge** pour évaluer automatiquement les résultats\n",
|
| 630 |
-
"6. **Effectuer une évaluation hors ligne** avec un jeu de données de référence\n",
|
| 631 |
-
"\n",
|
| 632 |
-
"🤗 Bon codage !"
|
| 633 |
-
]
|
| 634 |
-
}
|
| 635 |
-
],
|
| 636 |
-
"metadata": {
|
| 637 |
-
"kernelspec": {
|
| 638 |
-
"display_name": "Python 3 (ipykernel)",
|
| 639 |
-
"language": "python",
|
| 640 |
-
"name": "python3"
|
| 641 |
-
},
|
| 642 |
-
"language_info": {
|
| 643 |
-
"codemirror_mode": {
|
| 644 |
-
"name": "ipython",
|
| 645 |
-
"version": 3
|
| 646 |
-
},
|
| 647 |
-
"file_extension": ".py",
|
| 648 |
-
"mimetype": "text/x-python",
|
| 649 |
-
"name": "python",
|
| 650 |
-
"nbconvert_exporter": "python",
|
| 651 |
-
"pygments_lexer": "ipython3",
|
| 652 |
-
"version": "3.12.7"
|
| 653 |
-
}
|
| 654 |
-
},
|
| 655 |
-
"nbformat": 4,
|
| 656 |
-
"nbformat_minor": 4
|
| 657 |
-
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|