Gemini 中文指南
获取 API 密钥 ↗

Live API 最佳实践

↓ 下载 MarkdownInteractions API

本指南涵盖了您可以遵循的最佳实践,以优化 Live API 的使用。参见 开始使用 Live API 页面,了解常见用例的概述和示例代码。

设计清晰的系统指令 #

为了获得 Live API 的最佳性能,我们建议拥有一组明确定义的系统指令 (SI),按此顺序定义智能体角色、对话规则和护栏。

为了获得最佳结果,请将每个智能体分成不同的 SI。

  1. 指定智能体角色: 提供有关智能体的名称、角色和任何首选特征的详细信息。如果您想指定口音,请务必同时指定首选输出语言(例如说英语的人的英国口音)。

  2. 指定对话规则: 按照您期望模型遵循的顺序排列这些规则。区分对话的一次性元素和对话循环。例如:

  • 一次性元素: 收集一次客户的详细信息(例如姓名、位置、会员卡号)。
  • 对话循环: 用户可以讨论推荐、定价、退货和交付,并且可能想要从一个主题转到另一个主题。让模型知道只要用户愿意,就可以参与这个对话循环。
  1. 在不同的句子中指定流程内的工具调用: 例如,如果收集客户详细信息的一次性步骤需要调用 get_user_info 函数,你可能会说: 您的第一步是收集用户信息。首先,要求用户提供姓名、位置和会员卡号。然后调用 get_user_info 有了这些细节。

  2. 添加任何必要的护栏: 提供您不希望模型执行的任何一般对话护栏。请随意提供具体的例子 x 发生时,你希望模型做 y。如果您仍然没有达到首选的精度级别,请使用这个词 毫无疑问地 来指导模型的精确性。

精确定义工具 #

将工具与 Live API 一起使用时,请明确工具定义。请务必告知 Gemini 在什么条件下应调用工具调用。有关更多详细信息,请参阅 工具定义 在示例部分。

制作有效的提示 #

  • 使用清晰的提示: 提供模型在提示中应该做什么和不应该做什么的示例,并尝试将提示限制为每个角色或角色一次只有一个提示。考虑使用提示链,而不是冗长的多页提示。该模型在具有单个函数调用的任务上表现最佳。

  • 提供启动命令和信息: Live API 在响应之前等待用户输入。要让 Live API 发起对话,请包含一个提示,要求其问候用户或开始对话。包含有关用户的信息,以便 Live API 个性化该问候语。

指定语言 #

如果您希望模型以特定语言响应,请在系统说明中包含以下说明:

代码
RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.

流式输出 #

实施实时音频时,请遵循以下最佳实践:

  • 块大小和延迟:以 20 毫秒到 40 毫秒的块发送音频。
  • 中断处理:当用户在模型回复时说话时,服务器会发送一个 server_content 消息与 "interrupted": true。您必须立即丢弃客户端音频缓冲区,以防止智能体继续与用户交谈。

上下文管理 #

使用 ContextWindowCompressionConfig 对于长时间会话,因为本机音频 token 快速累积(每秒音频大约 25 token)。

客户端缓冲 #

在发送之前不要显着缓冲输入音频(例如 1 秒)。发送小块(20 毫秒 - 100 毫秒)以最大限度地减少延迟。

重采样 #

确保您的客户端应用程序在传输前将麦克风输入(通常为 44.1kHz 或 48kHz)重新采样为 16kHz。

会话管理 #

请遵循以下准则来处理会话生命周期并确保可靠的用户体验:

  • 启用上下文窗口压缩: 音频 token 以大约每秒 25 token 的速度累积。如果不进行压缩,纯音频会话将限制为 15 分钟,音频-视频会话将限制为 2 分钟。启用 上下文窗口压缩 将会话无限期延长。
  • 实现会话恢复: 服务器可能会定期重置 WebSocket 连接。使用 会话恢复 无缝地重新连接而不丢失上下文。保留最新的恢复token SessionResumptionUpdate 消息并在重新连接时将其作为句柄传递。恢复 token 在最后一次会话终止后的 2 小时内有效。
  • 处理 GoAway 消息: 服务器发送一个 走开 终止连接之前的消息。收听此消息并使用 timeLeft 在连接关闭之前优雅地结束或重新连接的字段。
  • 处理生成完整信号: 使用 generationComplete 消息以了解模型何时完成生成响应,以便您的应用程序可以更新其 UI 或继续执行下一步操作。

实现细节请参见 会话管理.

示例 #

该示例结合了最佳实践和 系统指令设计指南 指导模特作为职业教练的表现。

代码
**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat back what the client says back to them.
Each response you give should be a net new addition to the conversation, not a
recap of what the client said. Be relatable by bringing in your own background
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.

工具定义 #

此 JSON 定义了职业教练示例中调用的相关函数。为了在定义函数时获得最佳结果,请包括它们的名称、描述、参数和调用条件。

json
[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]

定价和计费 #

Gemini Live API 严格按照 token 使用情况计费。由于 Live API 维护持久的 WebSocket 会话,因此计费遵循基于活动上下文窗口的复合模型。

会话上下文窗口(复利成本) #

API 每轮向您收取会话上下文窗口中出现的所有 token 的费用。 “回合”被定义为一个用户输入和模型的相应响应。

  • 累积: 上下文窗口包括当前回合中的新 token 以及之前回合中所有累积的 token。
  • 重新计费: 过去的 token 会在每个新回合中重新处理和计算,最多可达您配置的上下文窗口大小。随着会话时间的延长,每轮的成本会增加,因为会话历史记录会被重新处理。

音频 token 和转录 #

Live API 本身就是多模态的。它将对话历史记录保留为原始音频 token,以保留声音的细微差别和音调。

  • 音频计费: API 每回合都会以标准音频输入速率向您收取累积的本机音频 token 的费用。
  • 转录附加费: 当启用音频到文本转录时(inputAudioTranscription 或 outputAudioTranscription),除了标准音频 token 费用外,API 还对以文本 token 输出速率转录而生成的所有文本 token 收取费用。

在环境限制下管理成本 #

为了防止长时间会话中成本无限增长,请使用以下命令配置上下文窗口大小 contextWindowCompression.

通过设置压缩触发器(例如,25,000 token)和滑动窗口(例如,8,000 token),一旦达到阈值,API就会自动驱逐旧的token。然后,API 仅对保留的历史记录和任何新的 token 的后续轮次进行计费。

主动音频模式 #

启用主动音频模式时,输入 token 在 Live API 监听的整个过程中都会充电,而输出 token 仅在 API 响应时充电。

  • Gemini 3.8 和 3.1 的注意事项: 支持主动音频模式 gemini-3.8-live 和 gemini-3.8-live-extended-thinking。不支持 gemini-3.1-flash-live-preview;对于该型号,您只需在主动流输入时支付音频费用。

有关详细定价信息,请参阅 Gemini API 定价页面.

搜索标题、API 名称或正文内容