Intégration SDK
Capturer les données
Au-delà des steps, vous émettez les données qui rendent une trace exploitable : entrées/sorties, métriques, logs. Tout se rattache au step (ou au flow) courant.
payload — entrées, sorties, contexte
Un payload porte un descripteur Data (rôle, type, format) et le contenu lui-même.
from niaone_sdk.models import Datafrom niaone_sdk.enums import DataRole, DataKind, DataFormat# entréepayload(step, "input", Data(role=DataRole.INPUT, kind=DataKind.MESSAGES, format=DataFormat.JSON), {"messages": [{"role": "user", "content": "Comment réinitialiser mon mot de passe ?"}]})# sortiepayload(step, "output", Data(role=DataRole.OUTPUT, kind=DataKind.COMPLETION, format=DataFormat.TEXT), "Allez dans Réglages → Sécurité…")| Data.role | Data.kind (exemples) | Data.format |
|---|---|---|
| INPUT / OUTPUT | MESSAGES, COMPLETION, TOOL_ARGS, TOOL_RESULT | TEXT |
| CONTEXT | RETRIEVAL_CONTEXT, DOCUMENT_CHUNK, PROMPT_TEMPLATE | JSON |
| ARTIFACT | PREDICTIONS, FEATURE_VECTOR, GROUND_TRUTH | ARRAY / OBJECT |
metric — mesures quantitatives
Émettez une métrique ponctuelle, ou accumulez-en sur le step (mergées à end_step). Préférez les
clés standardisées (StandardMetric) pour que le cockpit les agrège correctement.
# ponctuelmetric(step, "latency_ms", 950, unit="ms")# accumulé puis flush par end_stepstep.add_metrics({"input_tokens": 45, "output_tokens": 120})end_step(step, "success")| StandardMetric | unité | sens |
|---|---|---|
| input_tokens / output_tokens | count | Tokens d'entrée / sortie |
| total_tokens | count | Total tokens |
| cost_usd | usd | Coût estimé |
| latency_ms / duration_ms | ms | Latence / durée |
| time_to_first_token_ms | ms | TTFT (streaming) |
| tokens_per_second | count | Débit de génération |
| cache_read_tokens | count | Tokens lus depuis le cache |
| error_count / retry_count | count | Erreurs / retries |
| chunks_retrieved / chunks_relevant | count | RAG |
Tokens LLM en un appel
Inutile de mapper les tokens à la main : trace_llm_call(step, response) normalise l'usage
OpenAI / Anthropic / Gemini et émet la complétion. Voir Instrumentation LLM.
log — logs rattachés au span
log(step, "warning", "réponse tronquée, retry conseillé")