LLM Observability Experimentos es compatible con todo el ciclo de vida de la creación de aplicaciones y agentes LLM. Te ayuda a comprender cómo afectan al rendimiento los cambios en los avisos, los modelos, los proveedores o la arquitectura del sistema. Con esta función, puedes:

• Crear conjuntos de datos y versiones
• Ejecución y gestión de experimentos
• Comparar los resultados para evaluar el impacto

Instalación

1. Instala el kit de desarrollo de software (SDK) de Python de LLM Observability de Datadog:

   pip install ddtrace>=3.15.0
   

2. Activar LLM Observability:

   from ddtrace.llmobs import LLMObs
   
   LLMObs.enable(
       api_key="<YOUR_API_KEY>",  # defaults to DD_API_KEY environment variable
       app_key="<YOUR_APP_KEY>",  # defaults to DD_APP_KEY environment variable
       site="datadoghq.com",      # defaults to DD_SITE environment variable
       project_name="<YOUR_PROJECT>"  # defaults to DD_LLMOBS_PROJECT_NAME environment variable, or "default-project" if the environment variable is not set
   )
   

   Debes proporcionar tanto una clave_api como una clave_aplicación.

Proyectos

Los proyectos son el núcleo organizativo de LLM Experiments. Todos los conjuntos de datos y experimentos están en un project (proyecto). Puedes crear un project (proyecto) manualmente en la consola, la API o el kit de desarrollo de software (SDK) de Datadog especificando un nombre de project (proyecto) que no exista ya en LLMObs.enable.

LLMObs.enable(
    ...
    project_name="<YOUR_PROJECT>"  # defaults to DD_LLMOBS_PROJECT_NAME environment variable, or "default-project" if the environment variable is not set
)

Conjuntos de datos

Un conjunto de datos es una colección de entradas y resultados esperados y metadatos que representan escenarios en los que deseas probar tu agente. Cada conjunto de datos está asociado a un project (proyecto).

• entrada (obligatorio): Representa toda la información a la que el agente puede acceder en una tarea.
• salida esperada (opcional): También llamada verdad de base, representa la respuesta ideal que el agente debería emitir. Puedes utilizar la salida esperada para almacenar la salida real de la aplicación, así como cualquier resultado intermedio que desees evaluar.
• metadatos (opcional): Contiene cualquier información útil para categorizar el registro y utilizarlo para análisis posteriores. Por ejemplo: temas, tags (etiquetas), descripciones, notas.

Creación de un conjunto de datos

Puedes construir conjuntos de datos a partir de los datos de producción en la interfaz de usuario de Datadog seleccionando Add to Dataset (Añadir a conjunto de datos) en cualquier page (página) de span (tramo) o mediante programación utilizando el kit de desarrollo de software (SDK):

# Create dataset from CSV
dataset = LLMObs.create_dataset_from_csv(
    csv_path="questions.csv",
    dataset_name="capitals-of-the-world",
    project_name="capitals-project",              # Optional: defaults to the project name from LLMObs.enable
    description="Geography quiz dataset",         # Optional: Dataset description
    input_data_columns=["question", "category"],  # Columns to use as input
    expected_output_columns=["answer"],           # Optional: Columns to use as expected output
    metadata_columns=["difficulty"],              # Optional: Additional columns as metadata
    csv_delimiter=","                             # Optional: Defaults to comma
)

# Example "questions.csv":
# question,category,answer,difficulty
# What is the capital of Japan?,geography,Tokyo,medium
# What is the capital of Brazil?,geography,Brasília,medium

from ddtrace.llmobs import LLMObs

dataset = LLMObs.create_dataset(
    dataset_name="capitals-of-the-world",
    project_name="capitals-project", # optional, defaults to project_name used in LLMObs.enable
    description="Questions about world capitals",
    records=[
        {
            "input_data": {"question": "What is the capital of China?"},       # required, JSON or string
            "expected_output": "Beijing",                                      # optional, JSON or string
            "metadata": {"difficulty": "easy"}                                 # optional, JSON
        },
        {
            "input_data": {"question": "Which city serves as the capital of South Africa?"},
            "expected_output": "Pretoria",
            "metadata": {"difficulty": "medium"}
        }
    ]
)

# View dataset in Datadog UI
print(f"View dataset: {dataset.url}")

Recuperar un conjunto de datos

Para recuperar un conjunto de datos existente de un project (proyecto) en Datadog:

dataset = LLMObs.pull_dataset(
    dataset_name="capitals-of-the-world",
    project_name="capitals-project" # optional, defaults to the project name from LLMObs.enable
)

# Get dataset length
print(len(dataset))

Exportar un conjunto de datos a pandas

La clase Conjunto de datos también proporciona el método as_dataframe(), que permite transformar un conjunto de datos como un DataFrame de Pandas.

# Convert dataset to pandas DataFrame
df = dataset.as_dataframe()
print(df.head())

# DataFrame output with MultiIndex columns:
#                                   input_data     expected_output  metadata
#    question                       category       answer           difficulty
# 0  What is the capital of Japan?  geography      Tokyo            medium
# 1  What is the capital of Brazil? geography      Brasília         medium

El DataFrame tiene una estructura de MultiIndex con las siguientes columnas:

• input_data: Contiene todos los campos de entrada de input_data_columns
• expected_output: Contiene todos los campos de salida de expected_output_columns
• metadata: Contiene los campos adicionales de metadata_columns

Versiones de conjuntos de datos

Los conjuntos de datos se versionan automáticamente para rastrear los cambios a lo largo del tiempo. La información sobre las versiones facilita la reproducibilidad y permite que los experimentos hagan referencia a versiones específicas de los conjuntos de datos.

El objeto Dataset tiene un campo, current_version, que corresponde a la última versión; las versiones anteriores están sujetas a un plazo de retención de 90 días.

Las versiones de los conjuntos de datos comienzan en 0 y cada nueva versión se incrementa en 1.

Cuando se crean nuevas versiones de los conjuntos de datos

Se crea una nueva versión del conjunto de datos cuando:

• Se añaden registros
• Se actualizan registros (cambios en los campos input o expected_output )
• Se eliminan registros

Las versiones de los conjuntos de datos NO se crean para los cambios en los campos de metadata o cuando se actualiza el nombre o la descripción del conjunto de datos.

Retención de versiones

• Las versiones anteriores (NO el contenido de current_version) se retienen durante 90 días.
• El periodo de retención de 90 días se reinicia cuando se utiliza una versión anterior, por ejemplo, cuando un experimento lee una versión.
• Después de 90 días consecutivos sin uso, una versión anterior es susceptible de eliminación permanente y ya no puede ser accesible.

Ejemplo de comportamiento de retención de versión

Después de publicar 12, 11 se convierte en una versión anterior con una ventana de 90 días. Transcurridos 25 días, ejecutas un experimento con la versión 11, lo que provoca que la ventana de 90 días se reinicie. Después de otros 90 días, durante los cuales no has utilizado la versión 11, se puede eliminar la versión 11.

Acceso y gestión de registros de conjuntos de datos

Puedes acceder a los registros del conjunto de datos utilizando la indexación estándar de Python:

# Get a single record
record = dataset[0]

# Get multiple records
records = dataset[1:3]

# Iterate through records
for record in dataset:
    print(record["input_data"])

La clase Conjunto de datos proporciona métodos para gestionar los registros: append() update() , delete(). Es necesario push() cambios para guardar los cambios en Datadog.

# Add a new record
dataset.append({
    "input_data": {"question": "What is the capital of Switzerland?"},
    "expected_output": "Bern",
    "metadata": {"difficulty": "easy"}
})

# Update an existing record
dataset.update(0, {
    "input_data": {"question": "What is the capital of China?"},
    "expected_output": "Beijing",
    "metadata": {"difficulty": "medium"}
})

# Delete a record
dataset.delete(1)  # Deletes the second record

# Save changes to Datadog
dataset.push()

Experimentos

Los experimentos te permiten test sistemáticamente tu aplicación de LLM ejecutando tu agente a través de un conjunto de escenarios de tu conjunto de datos y midiendo el rendimiento con respecto a los resultados esperados utilizando evaluadores. Así podrás comparar el rendimiento de distintas configuraciones de la aplicación.

Tarea

La tarea define el workflow (UI) / proceso (generic) central que deseas evaluar. Puede variar desde una única llamada de LLM hasta un flujo más complejo que incluya varias llamadas de LLM y pasos de RAG. La tarea se ejecuta secuencialmente en todos los registros del conjunto de datos.

Evaluadores

Los evaluadores son funciones que se ejecutan en cada registro y que miden el rendimiento del modelo o agente. Permiten comparar la salida con la salida_esperada o con la entrada original.

Datadog admite los siguientes tipos de evaluadores:

• Booleano: devuelve true o false
• puntuación: devuelve un valor numérico (float)
• categorico: devuelve una categoría etiquetada (cadena)

Evaluadores de resumen

Los evaluadores de resumen son funciones opcionales que se ejecutan con todos los datos del experimento (entrada, salida, resultados esperados, resultados de los evaluadores). Los evaluadores de resumen permiten calcular métricas más avanzadas, como la precisión, la recuperación y la exactitud en todo el conjunto de datos.

Datadog admite los siguientes tipos de evaluadores de resumen:

• Booleano: devuelve true o false
• puntuación: devuelve un valor numérico (float)
• categórico: devuelve una categoría etiquetada (cadena)

Crear un experimento

1. Cargar un conjunto de datos

   from ddtrace.llmobs import LLMObs
   from typing import Dict, Any, Optional, List
   
   dataset = LLMObs.pull_dataset("capitals-of-the-world")
   

2. Definir una función de tarea que procese un único registro del conjunto de datos

   def task(input_data: Dict[str, Any], config: Optional[Dict[str, Any]] = None) -> str:
       question = input_data["question"]
       # Your LLM or processing logic here
       return "Beijing" if "China" in question else "Unknown"
   

   Una tarea puede tomar cualquier tipo no nulo como input_data (cadena, número, booleano, objeto, matriz). La salida que se utilizará en los evaluadores puede ser de cualquier tipo. Este ejemplo genera una cadena, pero se puede generar un diccionario como salida para almacenar cualquier información intermedia y comparar en los evaluadores.

   Puedes rastrear las diferentes partes de tu tarea de experimento (workflow (UI) / proceso (generic), llamadas a herramientas, etc.) utilizando los mismos decoradores de rastreo que utilizas en producción. Si utilizas un marco admitido (OpenAI, Amazon Bedrock, etc.), LLM Observability rastrea y anota automáticamente las llamadas a marcos y bibliotecas de LLM y te proporciona una observabilidad predefinida de las llamadas que realiza tu aplicación de LLM.

3. Define funciones de evaluadores.

   def exact_match(input_data: Dict[str, Any], output_data: str, expected_output: str) -> bool:
       return output_data == expected_output
   
   def overlap(input_data: Dict[str, Any], output_data: str, expected_output: str) -> float:
       expected_output_set = set(expected_output)
       output_set = set(output_data)
   
       intersection = len(output_set.intersection(expected_output_set))
       union = len(output_set.union(expected_output_set))
   
       return intersection / union
   
   def fake_llm_as_a_judge(input_data: Dict[str, Any], output_data: str, expected_output: str) -> str:
       fake_llm_call = "excellent"
       return fake_llm_call
   

   Las funciones de evaluadores pueden tomar cualquier tipo no nulo como input_data (cadena, número, booleano, objeto, matriz); output_data y expected_output pueden ser de cualquier tipo. Los evaluadores solo pueden devolver una cadena, un número o un booleano.

4. (Opcional) Define la(s) función(es) de evaluador(es) de resumen.

    def num_exact_matches(inputs, outputs, expected_outputs, evaluators_results):
        return evaluators_results["exact_match"].count(True)
   

   Si se definen y se proporcionan al experimento, las funciones del evaluador de resumen se ejecutan después de que los evaluadores hayan terminado de ejecutarse. Las funciones de evaluadores de resumen pueden tomar una lista de cualquier tipo no nulo como inputs (cadena, número, booleano, objeto, matriz); outputs y expected_outputs pueden ser listas de cualquier tipo. evaluators_results es un diccionario de listas de resultados de evaluadores, con la clave del nombre de la función de evaluador. Por ejemplo, en el fragmento de código anterior, el evaluador de resumen num_exact_matches utiliza los resultados (una lista de booleanos) del evaluador exact_match para proporcionar un count del número de coincidencias exactas. Los evaluadores de resumen solo pueden devolver una cadena, un número o un booleano.

5. Crea y ejecuta el experimento.

   experiment = LLMObs.experiment(
       name="capital-cities-test",
       task=task,
       dataset=dataset,
       evaluators=[exact_match, overlap, fake_llm_as_a_judge],
       summary_evaluators=[num_exact_matches], # optional
       description="Testing capital cities knowledge",
       config={
           "model_name": "gpt-4",
           "version": "1.0"
       },
   )
   
   # Run the experiment
   results = experiment.run()  # Run on all dataset records
   
   # Process results
   for result in results.get("rows", []):
       print(f"Record {result['idx']}")
       print(f"Input: {result['input']}")
       print(f"Output: {result['output']}")
       print(f"Score: {result['evaluations']['evaluator']['value']}")
       if result['error']['message']:
           print(f"Error: {result['error']['message']}")
   

   Para aumentar la velocidad de ejecución del experimento, puedes activar el procesamiento paralelo:

   results = experiment.run(jobs=4)
   

   Para test tu pipeline en un subconjunto de los datos, utiliza:

   results = experiment.run(sample_size=10)
   

   Para detener la ejecución del experimento si se produce un error, utiliza:

   results = experiment.run(raise_errors=True)
   

6. Visualiza los resultados de tu experimento en Datadog.

   print(f"View experiment: {experiment.url}")
   

Instalación de un experimento automatizado en Continuous Integration Continuous Delivery

Puedes ejecutar un experiment manualmente o configurarlo para que se ejecute automáticamente en tus pipelines de Continuous Integration Continuous Delivery. Por ejemplo, ejecútalo con tu conjunto de datos en cada cambio para comparar los resultados con tu línea de base y detectar posibles regresiones.

GitHub Actions

Esta sección asume que has completado con éxito las secciones instalación, proyectos, conjuntos de datos y experimentos. Puedes utilizar el siguiente script de Python y el workflow (UI) / proceso (generic) de GitHub Actions como plantillas para ejecutar un experimento automáticamente cada vez que el código se envíe a tu repositorio.

Nota: Los archivos de workflow (UI) / proceso (generic) están en el directorio .github/workflows y deben utilizar la sintaxis YAML con la extensión .yml.

from ddtrace.llmobs import LLMObs
from typing import Dict, Any, Optional, List

LLMObs.enable(
    api_key="<YOUR_API_KEY>",  # defaults to DD_API_KEY environment variable
    app_key="<YOUR_APP_KEY>",  # defaults to DD_APP_KEY environment variable
    site="datadoghq.com",      # defaults to DD_SITE environment variable
    project_name="<YOUR_PROJECT>"  # defaults to DD_LLMOBS_PROJECT_NAME environment variable, or "default-project" if the environment variable is not set
)


dataset = LLMObs.create_dataset(
    dataset_name="capitals-of-the-world",
    project_name="capitals-project",  # optional, defaults to project_name used in LLMObs.enable
    description="Questions about world capitals",
    records=[
        {
            "input_data": {
                "question": "What is the capital of China?"
            },  # required, JSON or string
            "expected_output": "Beijing",  # optional, JSON or string
            "metadata": {"difficulty": "easy"},  # optional, JSON
        },
        {
            "input_data": {
                "question": "Which city serves as the capital of South Africa?"
            },
            "expected_output": "Pretoria",
            "metadata": {"difficulty": "medium"},
        },
    ],
)

def task(input_data: Dict[str, Any], config: Optional[Dict[str, Any]] = None) -> str:
    question = input_data["question"]
    # Your LLM or processing logic here
    return "Beijing" if "China" in question else "Unknown"


def exact_match(
    input_data: Dict[str, Any], output_data: str, expected_output: str
) -> bool:
    return output_data == expected_output


def overlap(
    input_data: Dict[str, Any], output_data: str, expected_output: str
) -> float:
    expected_output_set = set(expected_output)
    output_set = set(output_data)

    intersection = len(output_set.intersection(expected_output_set))
    union = len(output_set.union(expected_output_set))

    return intersection / union


def fake_llm_as_a_judge(
    input_data: Dict[str, Any], output_data: str, expected_output: str
) -> str:
    fake_llm_call = "excellent"
    return fake_llm_call


def num_exact_matches(inputs, outputs, expected_outputs, evaluators_results):
    return evaluators_results["exact_match"].count(True)


experiment = LLMObs.experiment(
    name="capital-cities-test",
    task=task,
    dataset=dataset,
    evaluators=[exact_match, overlap, fake_llm_as_a_judge],
    summary_evaluators=[num_exact_matches],  # optional
    description="Testing capital cities knowledge",
    config={"model_name": "gpt-4", "version": "1.0"},
)

results = experiment.run(jobs=4, raise_errors=True)

print(f"View experiment: {experiment.url}")

name: Experiment SDK Test

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    environment: protected-main-env # The job uses secrets defined in this environment
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13.0' # Or your desired Python version
      - name: Install Dependencies
        run: pip install ddtrace>=3.15.0 dotenv
      - name: Run Script
        run: python ./experiment_sdk_demo/main.py
        env:
          DD_API_KEY: ${{ secrets.DD_API_KEY }}
          DD_APP_KEY: ${{ secrets.DD_APP_KEY }}

Cookbooks

Para ver ejemplos detallados de lo que puedes hacer con LLM Experiments, consulta las notebooks de Jupyter provistas por Datadog.

API HTTP

Inicio rápido de Postman

Datadog recomienda encarecidamente importar la recopilación Experimentos Postman a Postman. La función Ver documentación de Postman puede ayudarte a entender mejor esta API.

Formato de solicitud

Ejemplo: Creación de un conjunto de datos

{
  "data": {
    "type": "datasets", # tipo de solicitud
    "atributos": {
        "name": "ejemplo de conjunto de datos",
        "description": "Ejemplo de descripción"
    }
  }
}

Formato de respuesta

Ejemplo: Recuperación de conjuntos de datos

{
    "data": [
        {
            "id": "4ac5b6b2-dcdb-40a9-ab29-f98463f73b4z",
            "type": "datasets",
            "attributes": {
                "created_at": "2025-02-19T18:53:03.157337Z",
                "description": "Description example",
                "name": "Dataset example",
                "updated_at": "2025-02-19T18:53:03.157337Z"
            }
        }
    ],
    "meta": {
        "after": ""
    }
}

Objeto Datos

Objeto: Page (página)

API de projects (proyectos)

Tipo de solicitud: projects

API de conjuntos de datos

Tipo de solicitud: datasets

API de Experimentos

**Tipo de solicitud: experiments

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Crea y monitoriza experimentos LLM con DatadogBLOG