Guida all'SDK Python

Il pacchetto dell'SDK KLA per Python è kla-otel-python. Importalo come kla_otel_python. Inizializza OpenTelemetry, aggiunge gli attributi GenAI di KLA ed esporta helper per il middleware FastAPI, la strumentazione LangChain, il campionamento e la pubblicazione delle valutazioni.

Installazione

pip install kla-otel-python

Per il quickstart con FastAPI:

pip install "kla-otel-python[fastapi]" uvicorn

Imposta servizio e collector prima dell'avvio dell'applicazione:

export OTEL_SERVICE_NAME=claims-agent-api
export KLA_TENANT_ID=kpmg-reporting
export OTEL_EXPORTER_OTLP_ENDPOINT=<kla-otlp-grpc-endpoint>
export KLA_PII_MASK=true

Prima traccia con FastAPI

Carica l'SDK prima di creare l'app e qualsiasi client di modello.

# main.py
import kla_otel_python
from fastapi import FastAPI
from kla_otel_python import add_genai_attributes, tracer
from kla_otel_python.middleware import KLATracingMiddleware
from kla_otel_python.semantic_conventions import GenAIAttributes

app = FastAPI()
app.add_middleware(KLATracingMiddleware)


@app.post("/messages")
async def create_message(payload: dict):
    with tracer.start_as_current_span("agent.reply") as span:
        prompt = str(payload.get("prompt", ""))

        add_genai_attributes(
            span,
            {
                GenAIAttributes.SYSTEM: "openai",
                GenAIAttributes.REQUEST_MODEL: "gpt-4o-mini",
                GenAIAttributes.USAGE_PROMPT_TOKENS: 24,
                GenAIAttributes.USAGE_COMPLETION_TOKENS: 12,
                GenAIAttributes.USAGE_TOTAL_TOKENS: 36,
            },
        )

        return {"response": f"Handled: {prompt}"}

Eseguilo:

uvicorn main:app --reload
curl -s http://localhost:8000/messages \
  -H 'content-type: application/json' \
  -d '{"prompt":"Summarize the claim"}'

Apri KLA Control Plane, vai al Lineage Explorer e filtra per claims-agent-api. Lo span dovrebbe includere gen_ai.system, gen_ai.request.model e gli attributi di utilizzo dei token.

LangChain

Installa l'extra LangChain e abilita l'instrumentor prima di costruire chain, agent o tool.

pip install "kla-otel-python[langchain]"

import kla_otel_python
from kla_otel_python.instrumentors import LangChainInstrumentor

LangChainInstrumentor().instrument()

Per span di modello espliciti:

from kla_otel_python import add_genai_attributes, tracer
from kla_otel_python.semantic_conventions import GenAIAttributes

with tracer.start_as_current_span("langchain.agent.answer") as span:
    result = chain.invoke({"input": "Review this transaction"})

    add_genai_attributes(
        span,
        {
            GenAIAttributes.SYSTEM: "openai",
            GenAIAttributes.REQUEST_MODEL: "gpt-4o-mini",
            GenAIAttributes.USAGE_TOTAL_TOKENS: result.get("usage", {}).get("total_tokens"),
        },
    )

Verifica del pacchetto

Il dry-run del pacchetto SDK viene eseguito in CI con:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*