Generación de un conjunto de datos de evaluación sintética (versión preliminar)

Si tu agente aún no tiene tráfico de producción, igualmente puedes crear un conjunto de datos de evaluación útil. El servicio de generación de datos de Microsoft Foundry sintetiza los pares de preguntas y respuestas del material que ya tiene: las instrucciones de un agente, un mensaje en línea o un documento de referencia que cargue. La salida es un conjunto de datos versionado sobre el que puede ejecutar evaluadores.

Hay tres tipos de origen de entrada disponibles y puede combinarlos en un solo trabajo para una cobertura más completa:

• Definición del agente—generación de semillas a partir de las instrucciones o del prompt de un agente desplegado.
• Indicación: pasa una indicación de texto insertado que describe el dominio o que orienta la dificultad.
• Archivo de referencia: cargue un documento (por ejemplo, una directiva, especificación o exportación de base de conocimiento) y genere preguntas basadas en su contenido.

La generación sintética y la generación basada en seguimiento son complementarias: los conjuntos de datos sintéticos cubren casos perimetrales y escenarios previos, mientras que los conjuntos de datos basados en seguimiento reflejan el comportamiento real de producción. El uso de ambos proporciona la señal de evaluación más fuerte. Consulte Conversión de seguimientos del agente en conjuntos de datos de evaluación.

Cuándo usar la generación sintética

Use la generación sintética cuando:

• Está en prelanzamiento y todavía no hay seguimientos de producción.
• Su agente tiene poco tráfico y una ventana de seguimiento no proporciona suficientes muestras diferenciadas.
• Necesita una línea base de regresión estable que no se desfase con el cambio del comportamiento de producción.
• Conviene ampliar la cobertura de casos perimetrales que el agente no ha encontrado en producción.
• Usted está iterando sobre las instrucciones de un agente y necesita un conjunto de datos de prueba de humo rápido.

Elección de un tipo de origen

Puede combinar fuentes en un solo trabajo. Un patrón habitual es combinar un archivo de referencia (como base) con una instrucción (para orientar el tono o el nivel de dificultad).

Prerrequisitos

• versión del SDK de Python 2.2.0 o posterior: pip install "azure-ai-projects>=2.2.0" azure-identity.
• Dirección URL del punto de conexión del proyecto de Microsoft Foundry con el formato https://<your-resource>.services.ai.azure.com/api/projects/<your-project>.
• Rol de usuario de Foundry o superior en el proyecto.
• Una implementación de un modelo de Azure OpenAI que admite la API de respuestas. La simple_qna receta usa este modelo para sintetizar pares de preguntas y respuestas. Para ver la lista de modelos compatibles, consulte Compatibilidad de modelos de la API de respuestas de Azure OpenAI.

Regiones admitidas para la generación de datos sintéticos

La generación de datos sintéticos se admite en las siguientes regiones:

• Norte de Emiratos Árabes Unidos
• Oeste de EE. UU. 3
• Centro-Norte de EE. UU
• Este de EE. UU.
• Oeste de Europa
• Centro-sur de EE. UU.
• Norte de Suiza
• Centro de Suecia
• Este de EE. UU. 2
• Oeste de EE. UU.
• Centro de Francia
• Norte de Sudáfrica
• Este de Australia
• Japón Oriental
• Sur de Reino Unido
• Norway East
• Poland Central
• South India
• Centro-oeste de Alemania
• Norte de Italia

Generación de un conjunto de datos desde el portal

1. En el portal, abra la pestaña Generación de datos . Seleccione Crear conjunto de datos y, a continuación, seleccione Generar sintético.
2. En Generar datos sintéticos, establezca Uso del conjunto de datos en Evaluación.
3. Confirm Task type is Simple Q&A. (Confirmar tipo de tarea es Q&A simple).
4. Seleccione un modelo de generador.
5. Proporcione una o varias entradas de origen: agente, solicitud o archivo de referencia.
6. Establezca Número máximo de muestras y Nombre de archivo de salida.
7. Selecciona Generar.
8. Realice un seguimiento del estado del trabajo de generación de conjuntos de datos en la pestaña Generación de datos .
9. Cuando finalice el trabajo, obtenga una vista previa de las filas generadas en la pestaña Datos .

Generación de un conjunto de datos a partir de una definición de agente (SDK)

Este flujo inicia la generación a partir de las instrucciones de un agente implementado. El servicio captura el mensaje del agente y usa el modelo configurado para sintetizar pares de preguntas y respuestas a partir de él.

En primer lugar, cree un AIProjectClient usando el punto de conexión del proyecto y DefaultAzureCredential. Puede encontrar todas las operaciones de generación de datos en project_client.beta.datasets.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

credential = DefaultAzureCredential()
project_client = AIProjectClient(
    endpoint="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>",
    credential=credential,
)

A continuación, envíe un trabajo SimpleQnA cuyo origen sea una referencia de agente. Si ya tiene un agente implementado, omita la llamada create_version y pase su name y version existentes a AgentDataGenerationJobSource.

import time
from azure.ai.projects.models import (
    AgentDataGenerationJobSource,
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    DatasetDataGenerationJobOutput,
    JobStatus,
    PromptAgentDefinition,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"
TERMINAL_STATUSES = {JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.CANCELLED}

# 1. Reference (or create) a prompt agent whose instructions seed generation.
agent = project_client.agents.create_version(
    agent_name="retail-agent",
    definition=PromptAgentDefinition(
        model=MODEL_NAME,
        instructions=(
            "You are a customer support assistant for Contoso Retail. "
            "Answer questions about the product catalog, loyalty program, store hours, "
            "and the return policy. If a question falls outside this scope, say you "
            "don't have that information."
        ),
    ),
)

# 2. Define a SimpleQnA evaluation job sourced from the agent definition.
job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="retail-agent-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            AgentDataGenerationJobSource(
                description="Agent definition used to seed QnA generation.",
                agent_name=agent.name,
                agent_version=agent.version,
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            # Service requires max_samples to be between 15 and 1000.
            max_samples=15,
            # simple_qna requires model_options.
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="retail-agent-eval-set"),
    ),
)

# 3. Submit and poll until complete.
job = project_client.beta.datasets.create_generation_job(job=job)
print(f"Submitted {job.id} (status: {job.status})")

while job.status not in TERMINAL_STATUSES:
    time.sleep(10)
    job = project_client.beta.datasets.get_generation_job(job_id=job.id)
    print(f"  status: {job.status}")

if job.status != JobStatus.SUCCEEDED:
    message = job.error.message if job.error is not None else "<no error message>"
    raise RuntimeError(f"Job ended in {job.status}: {message}")

# 4. Resolve the generated dataset.
output_name = ""
output_version = ""
for output in (job.result.outputs if job.result is not None else None) or []:
    if isinstance(output, DatasetDataGenerationJobOutput):
        output_name = output.name or ""
        output_version = output.version or ""
        break

dataset = project_client.datasets.get(name=output_name, version=output_version)
print(f"Generated dataset: {dataset.name} v{dataset.version} (id: {dataset.id})")

La tarea genera un conjunto de datos versionado con campos query y ground_truth de un solo turno. Obtenga una vista previa en la pestaña Datos del portal para comprobar las filas generadas antes de evaluarla.

Generar un conjunto de datos a partir de un prompt (SDK)

Si aún no tiene un agente implementado o si desea generar datos a partir de un fragmento de código independiente del material de origen, pase el texto como .PromptDataGenerationJobSource Este enfoque es útil para documentos de directivas, contenido de preguntas frecuentes o especificaciones cortas.

from azure.ai.projects.models import (
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    JobStatus,
    PromptDataGenerationJobSource,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"

job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="contoso-refund-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            PromptDataGenerationJobSource(
                description="Contoso refund policy",
                prompt=(
                    "Contoso offers a full refund within 30 days of purchase for any product "
                    "returned in its original condition. After 30 days, store credit may be "
                    "issued at the discretion of customer support. Digital goods are "
                    "non-refundable once downloaded."
                ),
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            max_samples=15,
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="contoso-refund-eval-set"),
    ),
)

job = project_client.beta.datasets.create_generation_job(job=job)

Sondee y resuelva el conjunto de datos con el mismo patrón que se muestra en la sección anterior.

Generación de un conjunto de datos a partir de archivos de referencia (SDK)

Para material de origen más extenso, cargue un documento como archivo de Azure OpenAI y haga referencia a él mediante su identificador. Esta opción funciona mejor cuando el conocimiento del dominio del agente reside en un documento de especificación, exportación de base de conocimiento o directiva, ya que las preguntas generadas permanecen fundamentadas en ese contenido.

El archivo debe estar en estado processed para que el servicio de generación de datos pueda usarlo y debe contener al menos 1 KB de contenido.

Las extensiones de archivo de referencia admitidas son: .txt, , .md.csv.json.xml.html.pdf.png.jpg.jpeg.gif.tiff.tif.svg

import io
import time
from azure.ai.projects.models import (
    DataGenerationJob,
    DataGenerationJobInputs,
    DataGenerationJobOutputOptions,
    DataGenerationJobScenario,
    DataGenerationModelOptions,
    FileDataGenerationJobSource,
    JobStatus,
    SimpleQnADataGenerationJobOptions,
)

MODEL_NAME = "gpt-4.1-mini"
REFERENCE_DOCUMENT = open("retail-agent-reference.md", "rb").read()

# 1. Upload the reference document via the Azure OpenAI Files API.
openai_client = project_client.get_openai_client()
seed_file = openai_client.files.create(
    file=("retail-agent-reference.md", io.BytesIO(REFERENCE_DOCUMENT)),
    purpose="user_data",
)

# 2. Wait for the file to finish processing.
while seed_file.status not in ("processed", "error"):
    time.sleep(2)
    seed_file = openai_client.files.retrieve(file_id=seed_file.id)
if seed_file.status != "processed":
    raise RuntimeError(f"File failed to process: {seed_file.status}")

# 3. Submit a SimpleQnA job that references the uploaded file.
job = DataGenerationJob(
    inputs=DataGenerationJobInputs(
        name="retail-agent-file-eval-set",
        scenario=DataGenerationJobScenario.EVALUATION,
        sources=[
            FileDataGenerationJobSource(
                description="Contoso Retail product catalog and policy reference.",
                id=seed_file.id,
            ),
        ],
        options=SimpleQnADataGenerationJobOptions(
            max_samples=15,
            model_options=DataGenerationModelOptions(model=MODEL_NAME),
        ),
        output_options=DataGenerationJobOutputOptions(name="retail-agent-file-eval-set"),
    ),
)

job = project_client.beta.datasets.create_generation_job(job=job)

Ejecución de una evaluación en el conjunto de datos generado

El conjunto de datos generado utiliza el esquema estándar query y ground_truth, por lo que funciona directamente con las API de evaluación. Pase el name y la version del conjunto de datos (o su id) a su ejecución de evaluación.

Para obtener el flujo de evaluación completa, incluida la selección de evaluadores y la revisión de los resultados, consulte Ejecución de evaluaciones en la nube y Evaluación del agente.

Administración de trabajos de generación de datos

Use project_client.beta.datasets las API de administración de trabajos para enumerar, inspeccionar, cancelar y eliminar trabajos de generación sintética.

from azure.ai.projects.models import DataGenerationJobScenario

# List recent evaluation jobs.
for job in project_client.beta.datasets.list_generation_jobs(
    limit=20,
    order="desc",
    scenario=DataGenerationJobScenario.EVALUATION,
):
    print(f"{job.id}  {job.status:<12}  {job.inputs.name}")

# Inspect a specific job's status.
job = project_client.beta.datasets.get_generation_job(job_id="job_...")
print(f"{job.id}  {job.status}")

# Cancel a running job.
project_client.beta.datasets.cancel_generation_job(job_id="job_...")

# Delete a job record (produced datasets are not deleted).
project_client.beta.datasets.delete_generation_job(job_id="job_...")

Para más contexto, consulte Administración de trabajos de generación de datos.

Limitaciones

• Si el proyecto foundry está conectado a su propia cuenta de almacenamiento, el acceso a la red pública debe estar habilitado en esa cuenta de almacenamiento para la creación correcta del conjunto de datos.

procedimientos recomendados

• Refleje la indicación del sistema de producción. Al generar a partir de una definición de agente o un mensaje, use instrucciones que coincidan con lo que el agente de producción ejecuta realmente. El desfase aquí debilita la señal de evaluación.
• Combine un archivo de referencia con una indicación para obtener cobertura fundamentada. El archivo ancla preguntas generadas en contenido de dominio real; la indicación orienta el tono, la dificultad o el énfasis temático.
• Genere primero un lote pequeño. Empiece con el mínimo max_samples de 15, revise manualmente las filas de la pestaña Datos y, a continuación, aumente el valor cuando la calidad del resultado sea la adecuada.
• Vuelva a generar cuando cambien las instrucciones del agente. Un conjunto de datos generado a partir de una versión del mensaje de un agente se vuelve obsoleto cuando el mensaje cambia significativamente. Vuelva a ejecutar el trabajo y versione el nuevo resultado.
• Combine la generación sintética y la generación basada en trazas para lograr la máxima cobertura. Los datos sintéticos cubren lagunas antes del lanzamiento y para los casos perimetrales; los seguimientos de producción reflejan cómo se comporta realmente el agente. Use ambos orígenes juntos en lugar de tratarlos como alternativas. Consulte Conversión de seguimientos del agente en conjuntos de datos de evaluación.

Contenido relacionado

• Conversión de seguimientos del agente en conjuntos de datos de evaluación
• Evaluación del agente
• Ejecución de evaluaciones en la nube
• Configurar seguimiento para el agente