Subir ejemplos

Después de crear una instancia de Example Store, puedes comenzar a crear y subir ejemplos a ella. No hay límite para la cantidad de ejemplos que puedes almacenar en una instancia de Example Store. Los ejemplos estarán disponibles inmediatamente después de que los subas a la instancia de Example Store.

A continuación, se incluyen algunas situaciones en las que deberías subir ejemplos:

  • Las consultas no son relevantes para los ejemplos existentes.

  • El modelo tiene dificultades con algunos razonamientos.

  • Los ejemplos disponibles no abarcan todas las funciones, los resultados o el razonamiento que esperas.

Si creas ejemplos relevantes que tengan el formato esperado, puedes lograr lo siguiente:

  • Mejorar la capacidad del LLM para prestar atención a los ejemplos y usarlos, y evitar cambios inesperados en los patrones de respuesta que resultan de pequeños cambios en la instrucción

  • Reducir el posible impacto negativo de agregar ejemplos para consultas irrelevantes

  • El LLM funciona como se espera para consultas similares

Si el LLM muestra un comportamiento o razonamiento inesperado, puedes subir una respuesta corregida para guiar al modelo a seguir el patrón o razonamiento esperado en solicitudes posteriores.

Las muestras de esta página te permiten crear ejemplos basados en el resultado del LLM. La creación de ejemplos basados en el resultado de un LLM tiene las siguientes ventajas sobre la creación manual de ejemplos:

  • La creación de ejemplos basados en el resultado esperado del LLM implica menos esfuerzo manual.

  • Si creas ejemplos basados en el comportamiento inesperado del LLM, puedes corregir directamente los casos de falla.

  • Puedes crear ejemplos basados en respuestas de modelos con buen rendimiento para mejorar el comportamiento de otros modelos.

Usa ejemplos para mejorar el rendimiento de la llamada a función

Puedes usar algunos ejemplos para mejorar el rendimiento de la llamada a funciones demostrando lo siguiente: * Cuando se invoca una función en particular

  • Cómo extraer los argumentos para usar en la llamada a función

  • Cómo responde el modelo en función de la respuesta que muestra la función o varias funciones en caso de razonamiento de varios pasos

Para obtener más información sobre la llamada a función, consulta la documentación de Llamada a función.

Requisitos previos

Antes de usar las muestras de Python en esta página, debes instalar e inicializar el SDK de Agent Platform para Example Store en tu entorno local de Python.

  1. Ejecuta el siguiente comando para instalar el SDK de Agent Platform para Example Store.

    pip install --upgrade google-cloud-aiplatform>=1.87.0

  2. Usa la siguiente muestra de código para importar y, luego, inicializar el SDK para Example Store.

    import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto

    • LOCATION: Tu región. Solo se admite us-central1.

Subir ejemplos

Usa las siguientes muestras para subir ejemplos a una instancia de Example Store. Puedes subir un máximo de cinco ejemplos por solicitud.

Python

Las siguientes muestras te permiten mejorar el comportamiento del LLM y el rendimiento de la llamada a función creando y subiendo ejemplos a una instancia de Example Store con las respuestas recibidas de un LLM. Antes de usar las siguientes muestras, asegúrate de haber hecho lo siguiente:

Sigue las instrucciones de configuración de Python en las bibliotecas cliente y configura la autenticación con las credenciales predeterminadas de la aplicación.

Si deseas obtener más información, consulta la documentación de referencia de la API de Agent Platform para Python.

Sube un ejemplo basado en una respuesta esperada

Usa la siguiente muestra para crear y subir un ejemplo en una situación en la que la respuesta del LLM tenga el formato esperado. Esta muestra te permite enviar una solicitud, crear un ejemplo basado en la respuesta y, luego, subir el ejemplo a una instancia de Example Store.

from vertexai.preview.example_stores import ContentsExample, StoredContentsExample

client = genai.Client(
    http_options=genai_types.HttpOptions(api_version="v1"),
    vertexai=True,
    project="PROJECT_ID",
    location="LOCATION")

user_content = genai_types.Content(
    role="user",
    parts=[genai_types.Part(text="EXAMPLE_QUERY")],
)

response = client.models.generate_content(
    model="MODEL_NAME",
    user_content,
    config=genai_types.GenerateContentConfig(
      tools=[FUNCTION_OR_FUNCTION_DECLARATION]
    )
  )

# Upload example.
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": response.candidates[0].content.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

Reemplaza lo siguiente:

  • PROJECT_ID: ID del proyecto

  • LOCATION: Tu región. Solo se admite us-central1.

  • EXAMPLE_QUERY: La solicitud o consulta del usuario al LLM o al agente

  • MODEL_NAME: Es el nombre del modelo. Por ejemplo, gemini-2.0-flash.

  • FUNCTION_OR_FUNCTION_DECLARATION: La función o declaración de función que se usará en la solicitud Consulta la documentación del SDK de GenAI para la llamada a función si necesitas ayuda para definir una función como una herramienta.

  • EXPECTED_FUNCTION_RESPONSE: La respuesta de función esperada (un objeto FunctionResponse) para la llamada a función esperada Consulta la documentación del SDK de GenAI para la llamada a función si necesitas ayuda para definir una respuesta de función.

  • EXPECTED_FINAL_MODEL_RESPONSE: La respuesta final esperada del modelo (un objeto Content) para la llamada y la respuesta de función esperadas

Sube un ejemplo para corregir una respuesta inesperada

Si el LLM no genera la respuesta como se espera, puedes crear un ejemplo basado en la respuesta corregida. Esto ayuda al LLM a seguir el razonamiento esperado para solicitudes posteriores.

Usa la siguiente muestra para subir un ejemplo con la respuesta corregida a la instancia de Example Store.

user_content = genai_types.Content(
    role="user",
    parts=[genai_types.Part(text="EXAMPLE_QUERY")],
)

example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": EXPECTED_FUNCTION_CALL.to_json_dict()},
      {"content": EXPECTED_FUNCTION_RESPONSE.to_json_dict()},
      {"content": EXPECTED_FINAL_MODEL_RESPONSE.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}

example_store.upsert_examples(examples=[example])

Reemplaza lo siguiente:

REST

Para subir una muestra a una instancia de Example Store, envía una solicitud POST con el exampleStores.upsertExamples método.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: ID del proyecto
  • LOCATION: La región en la que deseas crear el almacén de ejemplos La única región admitida es us-central1.
  • EXAMPLE_STORE_ID: El ID de la instancia de Example Store en la que deseas subir el ejemplo

Método HTTP y URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples

Cuerpo JSON de la solicitud: 

{
  "examples": [
      {
          "stored_contents_example": {
              "contents_example": {
                  "contents": [
                      {
                          "role": "user",
                          "parts": [
                              {
                                  "text": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?"
                              }
                          ]
                      }
                  ],
                  "expected_contents": [
                      {
                          "content": {
                              "role": "model",
                              "parts": [
                                  {
                                      "text": ""Yes, there is a store located at 2000 N Shoreline Blvd, Mountain View, CA 94043, US."
                                  }
                              ]
                          }
                      }
                  ]
              },
              "search_key_generation_method": {
                  "last_entry": {}
              }
          }
      }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json, y ejecuta el siguiente comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json, y ejecuta el siguiente comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/exampleStores/EXAMPLE_STORE_ID:upsertExamples" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente, en la que EXAMPLE_ID representa el ID numérico generado para el ejemplo.

¿Qué sigue?