使用 Gemini 快速入門的範例商店

本教學課程說明如何反覆建立少量樣本，並從樣本儲存庫動態擷取這些樣本，藉此修正大型語言模型的行為。在本教學課程中，您會使用 gemini-2.0-flash 模型。 您將執行下列操作：

  • 建立 Example Store 執行個體 (ExampleStore)。

  • 根據 Gemini 的回覆製作範例，然後將這些範例上傳至範例商店執行個體。

  • 從樣本儲存庫動態擷取樣本，引導 LLM 做出預期行為。

  • 清除所用資源。

事前準備

如要完成本教學課程中示範的步驟，請先設定專案和環境。

設定專案

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI Agent Builder API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI Agent Builder API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.
  8. 如果您選取專案，請確認您具備專案的「Vertex AI 使用者」 (roles/aiplatform.user) IAM 角色。

向 Vertex AI 驗證

如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

  1. 安裝 Google Cloud CLI。

  2. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

    gcloud auth application-default login

    如果您使用 Cloud Shell，則不需要執行這項操作。

    如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「 為本機開發環境設定 ADC」。

匯入程式庫

  1. 執行下列指令，安裝 Example Store 的 Vertex AI SDK for Python。

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

  2. 使用下列程式碼範例，匯入及初始化 Example Store 的 SDK。

    import vertexai
from vertexai.preview import example_stores

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

    更改下列內容：

    • PROJECT_ID：專案 ID。

    • LOCATION：您的區域。系統僅支援 us-central1。

建立 Example Store 執行個體

使用下列程式碼範例，建立使用 text-embedding-005 嵌入模型的 Example Store 例項。

example_store = example_stores.ExampleStore.create(
    example_store_config=example_stores.ExampleStoreConfig(
        vertex_embedding_model="text-embedding-005"
    )
)

請注意，建立範例商店需要幾分鐘。

如要進一步瞭解如何建立或重複使用範例商店執行個體，請參閱「建立範例商店執行個體」。

將範例上傳至 Example Store 執行個體

請按照下列步驟，在 Example Store 執行個體中撰寫及上傳範例。每個要求最多可上傳五個範例。

  1. 定義 get_current_weather 函式工具。您在後續步驟中建立的範例，會引導模型瞭解何時要叫用這個函式，以及要將哪些引數傳遞給函式。

    如要進一步瞭解範例如何提升函式呼叫效能和模型回應，請參閱「使用範例提升函式呼叫效能」。如要進一步瞭解如何建立函式呼叫應用程式，請參閱「函式呼叫簡介」。

    from google.genai import types as genai_types

get_current_weather_func = genai_types.FunctionDeclaration(
  name="get_current_weather",
  description="Get the current weather in a given location",
  parameters={
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city name of the location for which to get the weather."
      }
    },
  },
)

  2. 使用 get_current_weather 函式傳送要求給 Gemini，生成內容。

    請參閱「建立 Gen AI SDK 的用戶端」。

    from google import genai

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=[Part(text="What is the weather like in Boston?")],
)
response = client.models.generate_content(
  model="gemini-2.0-flash",
  user_content,
  config=genai_types.GenerateContentConfig(
    tools=[
      genai_types.Tool(function_declarations=[get_current_weather_func])]
  )
)

  3. 請透過下列任一方式建立及上傳範例。

    • 如果 LLM 的回覆顯示預期行為，請使用下列程式碼範例，根據回覆撰寫範例，並上傳至範例商店。

      function_response = genai_types.Content(
  parts=[
    genai_types.Part(
      function_response={
        "name": "get_current_weather",
        "response": {
          "location": "New York, NY", "temperature": 38,
          "description": "Partly Cloudy",
          "icon": "partly-cloudy", "humidity": 65,
          "wind": { "speed": 10, "direction": "NW" }
        }
      }
    )
  ]
)
final_model_response = genai_types.Content(
  role="model",
  parts=[genai_types.Part(text="The weather in NYC is 38 degrees and partly cloudy.")],
)
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": response.candidates[0].content.to_json_dict()},
      {"content": function_response.to_json_dict()},
      {"content": final_model_response.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

    • 或者，如果回覆未涵蓋您預期的所有函式或結果，或是模型難以進行推論，請使用下列程式碼範例撰寫回覆，修正模型行為。

      expected_function_call = genai_types.Content(
  parts=[
    genai_types.Part(
      function_call={
        "name": "get_current_weather",
        "args": {"location": "New York, NY"}
      }
    )
  ]
)
function_response = genai_types.Content(
  parts=[
    genai_types.Part(
      function_response={
        "name": "get_current_weather",
        "response": {
          "location": "New York, NY", "temperature": 38,
          "description": "Partly Cloudy",
          "icon": "partly-cloudy", "humidity": 65,
          "wind": { "speed": 10, "direction": "NW" }
        }
      }
    )
  ]
)
final_model_response = genai_types.Content(
  role="model",
  parts=[genai_types.Part(text="The weather in NYC is 38 degrees and partly cloudy.")],
)
example = {
  "contents_example": {
    "contents": [user_content.to_json_dict()],
    "expected_contents": [
      {"content": expected_function_call.to_json_dict()},
      {"content": function_response.to_json_dict()},
      {"content": final_model_response.to_json_dict()},
    ],
  },
  "search_key": user_content.parts[0].text,
}
example_store.upsert_examples(examples=[example])

  4. 視需要重複步驟 2 和 3，製作及上傳多個範例。如果模型出現非預期行為，或上傳的範例未涵蓋您期望的所有功能、結果或推論，您可以上傳其他範例。如要進一步瞭解何時需要上傳其他範例，請參閱「上傳範例」。

使用 Gemini 擷取及運用範例

根據與提示的相似度搜尋範例。接著即可將這些範例新增至提示，引導 LLM 做出預期行為。

定義輔助函式來設定範例格式

使用下列程式碼範例定義 ExampleStorePrompt 類別和輔助函式，以便搜尋及擷取範例。

import abc
import jinja2
import json

from google.protobuf import json_format
# --BOILERPLATE CODE FOR FORMATTING--

EXAMPLES_PREAMBLE = """<EXAMPLES>
The following are examples of user queries and model responses using the available python libraries.

Begin few-shot
"""

EXAMPLES_POSTAMBLE = """
End few-shot

Now, try to follow these examples and complete the following conversation:
</EXAMPLES>
"""

EXAMPLE_PREAMBLE = "EXAMPLE"

TEMPLATE = """
"""

class ExampleStorePrompt:

    def __init__(
          self, template = TEMPLATE, example_preamble = EXAMPLE_PREAMBLE,
          examples_preamble = EXAMPLES_PREAMBLE,
          examples_postamble = EXAMPLES_POSTAMBLE):

        self.template = jinja2.Template(template)
        self.example_preamble = example_preamble
        self.examples_preamble = examples_preamble
        self.examples_postamble = examples_postamble

    @abc.abstractmethod
    def process_function_response(self, function_response):
        return json.dumps(function_response)

    @abc.abstractmethod
    def process_function_call(self, function_call):
        args_list = []
        for key, value in function_call.get("args", []).items():
            if isinstance(value, str):
                # Wrap strings in quotes.
                value = f'"{value}"'
            if isinstance(value, list):
                value = ', '.join(
                    f'"{item}"' if isinstance(item, str)
                    else str(item) for item in value)
                value = f"[{value}]"
            if isinstance(value, dict):
                value = json.dumps(value)
            args_list.append(f'{key}={value}')
        args = ", ".join(args_list)
        return f"```\n{function_call.get('name')}({args})\n```"

    @abc.abstractmethod
    def process_part(self, part):
        if "function_call" in part:
            return self.process_function_call(part["function_call"])
        if "text" in part:
            return part.get("text")
        if "function_response" in part:
            return self.process_function_response(part["function_response"])

    @abc.abstractmethod
    def process_content(self, content):
        response = []
        for part in content.get("parts", []):
            response.append(self.process_part(part))
        return [content.get("role"), response]

    @abc.abstractmethod
    def example_formatter(self, example: dict):
        response = []
        for content in example.get("contents", []):
            response.append(self.process_content(content))
        for content in example.get("expected_contents", []):
            content = content.get("content", {})
            response.append(self.process_content(content))
        return response

    def get_prompt(self, examples: list):
        if not examples:
          return ""
        contents_example = example.get("example", {}).get(
          "stored_contents_example", {}).get("contents_example", {})
        examples = [self.example_formatter(example) for example in examples]
        return self.template.render(
            examples=examples,
            example_preamble=self.example_preamble,
            examples_preamble=self.examples_preamble,
            examples_postamble=self.examples_postamble
        )

搜尋相關範例

使用下列程式碼範例，搜尋與 LLM 進行中對話相關的範例。接著，您可以使用輔助函式，在提示中加入這些範例。

query = "what's the fastest way to get to disney from lax"

# Search for relevant examples.
examples = example_store.search_examples(
  {"stored_contents_example_key": query}, top_k=3)

prompt = ExampleStorePrompt().get_prompt(examples.get("results", []))

model_response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="How do I get to LAX?",
    config=genai_types.GenerateContentConfig(
      system_instruction=prompt,
      tools=[
        genai_types.Tool(function_declarations=[track_flight_status_function])]
  )
)

反覆提升回覆品質

如要使用多樣本範例改善 Gemini 的回覆模式，請重複下列各節的步驟：

  1. 在範例商店執行個體中撰寫並上傳範例。

  2. 使用 Gemini 擷取及運用範例

清除所用資源

如要清理此專案中使用的所有資源，您可以刪除用於本快速入門導覽課程的 Google Cloud 專案。

或者，您也可以按照下列步驟，刪除在本教學課程中建立的個別資源：

  1. 使用下列程式碼範例刪除 Example Store 執行個體。

    example_store.delete()

  2. 刪除所有在本機建立的檔案。

後續步驟