上传示例

创建示例库实例后，您可以开始编写示例并将其上传到该实例。您可以在示例存储实例中存储的示例数量没有限制。您将示例上传到示例商店实例后，示例会立即可用。

需要上传示例的几种情况包括：

查询与现有示例不相关。
模型难以进行某些推理。
可用的示例并未涵盖您预期的所有函数、结果或推理。

通过编写符合预期格式的相关示例，您可以实现以下目标：

提高 LLM 注意并使用示例的能力，避免因对提示进行细微更改而导致响应模式发生意外更改。
减少为不相关的查询添加示例的潜在负面影响。
LLM 对类似查询的执行效果符合预期。

如果 LLM 显示意外行为或推理，您可以上传更正后的响应，以引导模型在后续请求中遵循预期的模式或推理。

借助本页上的示例，您可以根据 LLM 输出编写示例。与手动编写示例相比，基于 LLM 输出编写示例具有以下优势：

根据预期的 LLM 输出编写示例所需的手动工作量较少。
通过创建基于 LLM 意外行为的示例，您可以直接纠正失败案例。
您可以根据表现良好的模型的响应来编写示例，以改进其他模型的行为。例如，如果 Gemini 1.5 Pro 提供的响应优于 Gemini 1.5 Flash，但延迟时间更长，您可以使用这些响应编写示例，以便在使用 Gemini 1.5 Flash 时实现更低的延迟时间和类似的性能。

使用示例来提高函数调用性能

您可以使用少量示例来演示以下内容，从而提高函数调用性能：* 调用特定函数时。

如何提取要在函数调用中使用的参数。
模型根据函数（或多步推理中的多个函数）返回的响应做出响应的方式。

如需详细了解函数调用，请参阅函数调用文档。

前提条件

在使用本页上的 Python 示例之前，您必须在本地 Python 环境中安装并初始化适用于示例存储库的 Vertex AI SDK for Python。

运行以下命令以安装适用于示例商店的 Python 版 Vertex AI SDK。
```
pip install --upgrade google-cloud-aiplatform>=1.87.0
```
使用以下代码示例导入并初始化适用于示例商店的 SDK。
```
import vertexai
from vertexai.preview import example_stores

vertexai.init(
  project="PROJECT_ID",
  location="LOCATION"
)
```
替换以下内容：
- PROJECT_ID：您的项目 ID。
- LOCATION：您的区域。仅支持 us-central1。

上传示例

使用以下示例将示例上传到示例商店实例。每个请求最多可以上传 5 个示例。

Python

以下示例可让您使用从 LLM 收到的响应，创建示例并将其上传到示例存储区实例，从而改进 LLM 行为和函数调用性能。在使用以下示例之前，请确保您已完成以下操作：

按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。如需了解详情，请参阅 Vertex AI Python API 参考文档。
通过设置应用默认凭证向 Vertex AI 进行身份验证。如需了解详情，请参阅为本地开发环境设置身份验证。

上传符合预期响应的示例

在 LLM 的响应符合预期格式的情况下，使用以下示例编写并上传示例。借助此示例，您可以发送请求、根据响应创建示例，然后将示例上传到示例商店实例。

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 = Content(
    role="user",
    parts=[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])

替换以下内容：

PROJECT_ID：您的项目 ID。
LOCATION：您的区域。仅支持 us-central1。
EXAMPLE_QUERY：用户向 LLM 或代理发出的请求或查询。
MODEL_NAME：模型名称。例如 gemini-2.0-flash。
FUNCTION_OR_FUNCTION_DECLARATION：要在请求中使用的函数或函数声明。如需有关将函数定义为工具的帮助，请参阅 GenAI SDK 函数调用文档。
EXPECTED_FUNCTION_RESPONSE：预期函数调用的预期函数响应（FunctionResponse 对象）。如需有关定义函数响应的帮助，请参阅 GenAI SDK 函数调用文档。
EXPECTED_FINAL_MODEL_RESPONSE：预期函数调用和响应的预期最终模型响应（Content 对象）。

上传示例以更正非预期响应

如果 LLM 未按预期生成响应，您可以根据更正后的响应创建示例。这有助于 LLM 遵循后续请求的预期推理。

使用以下示例，将包含更正后的响应的示例上传到示例商店实例。

user_content = Content(
    role="user",
    parts=[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])

替换以下内容：

EXAMPLE_QUERY：用户向 LLM 或代理发出的请求或查询。
EXPECTED_FUNCTION_CALL：针对所提供的用户查询的预期函数调用（FunctionCall 对象）。如需有关定义函数调用的帮助，请参阅 GenAI SDK 函数调用文档。
EXPECTED_FUNCTION_RESPONSE：预期函数调用的预期函数响应（FunctionResponse 对象）。如需有关定义函数响应的帮助，请参阅 GenAI SDK 函数调用文档。
EXPECTED_FINAL_MODEL_RESPONSE：预期函数调用和响应的预期最终模型响应（Content 对象）。

REST

如需将示例上传到示例商店实例，请使用 exampleStores.upsertExamples 方法发送 POST 请求。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：要在其中创建示例商店的区域。仅支持区域 us-central1。
EXAMPLE_STORE_ID：要上传示例的示例商店实例的 ID。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "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": {}
              }
          }
      }
  ]
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该会收到类似以下示例的 JSON 响应，其中 EXAMPLE_ID 表示为示例生成的数字 ID。

响应

{
  "results": [
    {
      "example": {
        "exampleId": "exampleTypes/stored_contents_example/examples/EXAMPLE_ID",
        "storedContentsExample": {
          "searchKey": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?",
          "contentsExample": {
            "contents": [
              {
                "role": "user",
                "parts": [
                  {
                    "text": "Is there a store in Mountain View, CA that I can visit to try the new Pixel 8 Pro?"
                  }
                ]
              }
            ],
            "expectedContents": [
              {
                "content": {
                  "role": "model",
                  "parts": [
                    {
                      "text": ""Yes, there is a store located at 2000 N Shoreline Blvd, Mountain View, CA 94043, US."
                    }
                  ]
                }
              }
            ]
          },
          "searchKeyGenerationMethod": {
            "lastEntry": {}
          }
        }
      }
    }
  ]
}

后续步骤

了解如何检索示例。

上传示例 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用示例来提高函数调用性能

前提条件

上传示例

Python

上传符合预期响应的示例

上传示例以更正非预期响应

REST

curl

PowerShell

响应

后续步骤

上传示例