素问 - iOS技术

全文转载：OpenHarmony TaskPool 指定任务并发度场景

Wed, 17 Jun 2026 12:27:00 +0800

原文标题：OpenHarmony TaskPool 指定任务并发度场景

作者/来源：OpenHarmony docs contributors / OpenHarmony docs

原文链接：https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/arkts-utils/taskpool-async-task-guide.md

许可证/授权：Creative Commons Attribution 4.0 International (CC BY 4.0)

转载声明：本文完整转载自 OpenHarmony docs 开源文档仓库，按 CC BY 4.0 署名转载。本站转载仅用于技术学习与资料归档，已注明作者/来源与原文链接。如有侵权或不希望转载，请联系删除。

TaskPool指定任务并发度场景

TaskPool支持使用异步队列来控制任务的并发度，能有效避免资源过载，减少任务阻塞，适用于网络请求、视频流处理和数据库操作等场景。

此处提供使用TaskPool创建异步队列的开发指导，以相机预览流采集数据处理的功能为例。

由于处理过程是一个频繁且耗时的任务，当相机采集速度过快时，将丢弃之前的采集数据，仅保留最新的一帧数据进行处理。

导入需要用到的模块。

// TaskpoolAsyncLevel.ets
import { taskpool } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { PromptAction } from '@kit.ArkUI';

定义耗时任务。

// TaskpoolAsyncLevel.ets
@Concurrent
function collectFrame() {
  // 采集数据，并且进行处理
  // 模拟处理过程，这里是个耗时任务，持续时间为30秒
  let t = new Date().getTime()
  while (new Date().getTime() - t < 30000) {
    continue;
  }
  console.info('collectFrame finished');
}

创建异步队列并执行采集任务。

// TaskpoolAsyncLevel.ets
@Entry
@Component
struct TaskpoolAsyncLevel {
  @State message: string = '触发采集任务';
  @State returnMessage: string = 'return...';
  @State promptAction: PromptAction = this.getUIContext().getPromptAction();
  
  build() {
    Row() {
      Column() {
        Button(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(async () => {
            // 创建并发度为5的异步队列，等待队列个数为5，当加入的任务数量超过5时，等待列表中处于队头的任务会被丢弃
            let asyncRunner:taskpool.AsyncRunner = new taskpool.AsyncRunner('async', 5, 5);
            // 触发采集任务
            for (let i = 0; i < 20; i++) {
              let task:taskpool.Task = new taskpool.Task(`async${i}`,collectFrame);
              asyncRunner.execute(task).then(() => {
                console.info('the current task name is ' + task.name);
              }).catch((e:BusinessError) => {
                console.error('async: error is ' + e);
              });
            }
            console.info('asyncRunner task finished');
            this.returnMessage = 'asyncRunner task finished';
            this.promptAction.showToast({ message: this.returnMessage });
          })
        // ...
      }
      .width('100%')
    }
    .height('100%')
  }
}

全文转载：OpenHarmony UIAbility 组件概述

Wed, 17 Jun 2026 12:24:00 +0800

原文标题：OpenHarmony UIAbility 组件概述

作者/来源：OpenHarmony docs contributors / OpenHarmony docs

原文链接：https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/uiability-overview.md

许可证/授权：Creative Commons Attribution 4.0 International (CC BY 4.0)

UIAbility组件概述

概述

UIAbility组件是一种包含UI的应用组件，主要用于和用户交互。例如，图库类应用可以在UIAbility组件中展示图片瀑布流。

UIAbility的设计理念：

支持应用组件级的跨端迁移和多端协同。
支持多设备和多窗口形态。

UIAbility划分原则与建议：

UIAbility组件是系统调度的基本单元，为应用提供绘制界面的窗口。一个应用可以包含一个或多个UIAbility组件。例如，在支付应用中，可以将入口功能和收付款功能分别配置为独立的UIAbility。

每一个UIAbility组件实例都会在最近任务列表中显示一个对应的任务。

对于开发者而言，可以根据具体场景选择单个还是多个UIAbility，划分建议如下：

如果开发者希望在任务视图中看到一个任务，建议使用“一个UIAbility+多个页面”的方式，可以避免不必要的资源加载。
如果开发者希望在任务视图中看到多个任务，或者需要同时开启多个窗口，建议使用多个UIAbility实现不同的功能。

例如，即时通讯类应用中的消息列表与音视频通话采用不同的UIAbility进行开发，既可以方便地切换任务窗口，又可以实现应用的两个任务窗口在一个屏幕上分屏显示。

说明：

任务视图用于快速查看和管理当前设备上运行的所有任务或应用。

声明配置

为使应用能够正常使用UIAbility，需要在module.json5配置文件的abilities标签中声明UIAbility的名称、入口、标签等相关信息。

{
  "module": {
    // ···
    "abilities": [
      {
        "name": "EntryAbility", // UIAbility组件的名称
        "srcEntry": "./ets/entryability/EntryAbility.ets", // UIAbility组件的代码路径
        "description": "$string:EntryAbility_desc", // UIAbility组件的描述信息
        "icon": "$media:layered_image", // UIAbility组件的图标
        "label": "$string:EntryAbility_label", // UIAbility组件对用户显示的名称
        "startWindowIcon": "$media:startIcon", // UIAbility组件启动页面图标资源文件的索引
        "startWindowBackground": "$color:start_window_background", // UIAbility组件启动页面背景颜色资源文件的索引
        // ···
      }
    ]
    // ···
  }
}

全文转载：Gemini API 结构化输出

Wed, 17 Jun 2026 12:21:00 +0800

原文标题：Gemini API 结构化输出

作者/来源：Google AI for Developers / Google AI for Developers

原文链接：https://ai.google.dev/gemini-api/docs/structured-output?hl=zh-cn

许可证/授权：Creative Commons Attribution 4.0 / Apache 2.0 for code samples

转载声明：本文完整转载自 Google AI for Developers 官方中文文档。页面文字为 CC BY 4.0，代码示例为 Apache 2.0。本站转载仅用于技术学习与资料归档，已注明作者/来源与原文链接。如有侵权或不希望转载，请联系删除。

结构化输出

您可以配置 Gemini 模型，使其生成的回答符合提供的 JSON 架构。这样可以确保获得可预测的类型安全结果，并简化从非结构化文本中提取结构化数据的过程。

使用结构化输出非常适合以下情况：

数据提取：从文本中提取特定信息，例如姓名和日期。
结构化分类：将文本分类为预定义的类别。
智能体工作流：为工具或 API 生成结构化输入。

除了在 REST API 中支持 JSON 架构之外，Google GenAI SDK 还可让您使用 Pydantic (Python) 和 Zod (JavaScript) 轻松定义架构。

结构化输出示例

Recipe Extractor

此示例演示了如何使用 object、array、string 和 integer 等基本 JSON 架构类型从文本中提取结构化数据。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "response_format": {"text": {"mime_type": "application/json", "schema": Recipe.model_json_schema()}},
    },
)

recipe = Recipe.model_validate_json(response.text)
print(recipe)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ingredientSchema = z.object({
  name: z.string().describe("Name of the ingredient."),
  quantity: z.string().describe("Quantity of the ingredient, including units."),
});

const recipeSchema = z.object({
  recipe_name: z.string().describe("The name of the recipe."),
  prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
  ingredients: z.array(ingredientSchema),
  instructions: z.array(z.string()),
});

const ai = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: prompt,
  config: {
    responseFormat: { text: { mimeType: "application/json", schema: zodToJsonSchema(recipeSchema) } },
  },
});

const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `
  Please extract the recipe from the following text.
  The user wants to make delicious chocolate chip cookies.
  They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
  1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
  3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
  For the best part, they'll need 2 cups of semisweet chocolate chips.
  First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
  baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
  until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
  ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
  onto ungreased baking sheets and bake for 9 to 11 minutes.
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "recipe_name": map[string]any{
                    "type":        "string",
                    "description": "The name of the recipe.",
                },
                "prep_time_minutes": map[string]any{
                    "type":        "integer",
                    "description": "Optional time in minutes to prepare the recipe.",
                },
                "ingredients": map[string]any{
                    "type": "array",
                    "items": map[string]any{
                        "type": "object",
                        "properties": map[string]any{
                            "name": map[string]any{
                                "type":        "string",
                                "description": "Name of the ingredient.",
                            },
                            "quantity": map[string]any{
                                "type":        "string",
                                "description": "Quantity of the ingredient, including units.",
                            },
                        },
                        "required": []string{"name", "quantity"},
                    },
                },
                "instructions": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
            },
            "required": []string{"recipe_name", "ingredients", "instructions"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." }
        ]
      }],
      "generationConfig": {
        "responseFormat": {
          "text": {
            "mimeType": "application/json",
            "schema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
          }
        }
      },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
    }'

示例回答：

{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    {
      "name": "all-purpose flour",
      "quantity": "2 and 1/4 cups"
    },
    {
      "name": "baking soda",
      "quantity": "1 teaspoon"
    },
    {
      "name": "salt",
      "quantity": "1 teaspoon"
    },
    {
      "name": "unsalted butter (softened)",
      "quantity": "1 cup"
    },
    {
      "name": "granulated sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "packed brown sugar",
      "quantity": "3/4 cup"
    },
    {
      "name": "vanilla extract",
      "quantity": "1 teaspoon"
    },
    {
      "name": "large eggs",
      "quantity": "2"
    },
    {
      "name": "semisweet chocolate chips",
      "quantity": "2 cups"
    }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}

内容审核

此示例展示了 anyOf（用于条件架构）和 enum（用于分类），从而使输出结构能够根据内容而变化。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import Union, Literal

class SpamDetails(BaseModel):
    reason: str = Field(description="The reason why the content is considered spam.")
    spam_type: Literal["phishing", "scam", "unsolicited promotion", "other"] = Field(description="The type of spam.")

class NotSpamDetails(BaseModel):
    summary: str = Field(description="A brief summary of the content.")
    is_safe: bool = Field(description="Whether the content is safe for all audiences.")

class ModerationResult(BaseModel):
    decision: Union[SpamDetails, NotSpamDetails]

client = genai.Client()

prompt = """
Please moderate the following content and provide a decision.
Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'
"""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "response_format": {"text": {"mime_type": "application/json", "schema": ModerationResult.model_json_schema()}},
    },
)

result = ModerationResult.model_validate_json(response.text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const spamDetailsSchema = z.object({
  reason: z.string().describe("The reason why the content is considered spam."),
  spam_type: z.enum(["phishing", "scam", "unsolicited promotion", "other"]).describe("The type of spam."),
});

const notSpamDetailsSchema = z.object({
  summary: z.string().describe("A brief summary of the content."),
  is_safe: z.boolean().describe("Whether the content is safe for all audiences."),
});

const moderationResultSchema = z.object({
  decision: z.union([spamDetailsSchema, notSpamDetailsSchema]),
});

const ai = new GoogleGenAI({});

const prompt = `
Please moderate the following content and provide a decision.
Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'
`;

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: prompt,
  config: {
    responseFormat: { text: { mimeType: "application/json", schema: zodToJsonSchema(moderationResultSchema) } },
  },
});

const result = moderationResultSchema.parse(JSON.parse(response.text));
console.log(result);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `
  Please moderate the following content and provide a decision.
  Content: 'Congratulations! You''ve won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com'
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "decision": map[string]any{
                    "anyOf": []map[string]any{
                        {
                            "type":        "object",
                            "title":       "SpamDetails",
                            "description": "Details for content classified as spam.",
                            "properties": map[string]any{
                                "reason": map[string]any{
                                    "type":        "string",
                                    "description": "The reason why the content is considered spam.",
                                },
                                "spam_type": map[string]any{
                                    "type":        "string",
                                    "enum":        []string{"phishing", "scam", "unsolicited promotion", "other"},
                                    "description": "The type of spam.",
                                },
                            },
                            "required": []string{"reason", "spam_type"},
                        },
                        {
                            "type":        "object",
                            "title":       "NotSpamDetails",
                            "description": "Details for content classified as not spam.",
                            "properties": map[string]any{
                                "summary": map[string]any{
                                    "type":        "string",
                                    "description": "A brief summary of the content.",
                                },
                                "is_safe": map[string]any{
                                    "type":        "boolean",
                                    "description": "Whether the content is safe for all audiences.",
                                },
                            },
                            "required": []string{"summary", "is_safe"},
                        },
                    },
                },
            },
            "required": []string{"decision"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "Please moderate the following content and provide a decision.\nContent: ''Congratulations! You have won a free cruise to the Bahamas. Click here to claim your prize: www.definitely-not-a-scam.com''" }
        ]
      }],
      "generationConfig": {
        "responseFormat": {
          "text": {
            "mimeType": "application/json",
            "schema": {
          "type": "object",
          "properties": {
            "decision": {
              "anyOf": [
                {
                  "type": "object",
                  "title": "SpamDetails",
                  "description": "Details for content classified as spam.",
                  "properties": {
                    "reason": { "type": "string", "description": "The reason why the content is considered spam." },
                    "spam_type": { "type": "string", "enum": ["phishing", "scam", "unsolicited promotion", "other"], "description": "The type of spam." }
          }
        }
      },
                   "required": ["reason", "spam_type"]
                 },
                 {
                   "type": "object",
                   "title": "NotSpamDetails",
                   "description": "Details for content classified as not spam.",
                   "properties": {
                     "summary": { "type": "string", "description": "A brief summary of the content." },
                     "is_safe": { "type": "boolean", "description": "Whether the content is safe for all audiences." }
                   },
                   "required": ["summary", "is_safe"]
                 }
               ]
             }
           },
           "required": ["decision"]
         }
       }
     }'
 ```

**Example Response:**

```json
{
"decision": {
 "reason": "The content is an unsolicited prize notification attempting to trick the user into clicking a suspicious link.",
 "spam_type": "scam"
}
}

递归结构

此示例展示了如何定义递归架构，例如组织结构图。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List

class Employee(BaseModel):
    """Represents an employee in an organization."""
    name: str
    employee_id: int
    reports: List["Employee"] = Field(
        default_factory=list,
        description="A list of employees reporting to this employee."
    )

client = genai.Client()

prompt = """
Generate an organization chart for a small team.
The manager is Alice, who manages Bob and Charlie. Bob manages David.
"""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "response_format": {"text": {"mime_type": "application/json", "schema": Employee.model_json_schema()}},
    },
)

employee = Employee.model_validate_json(response.text)
print(employee)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const employeeSchema = z.object({
  name: z.string(),
  employee_id: z.number().int(),
  reports: z.lazy(() => z.array(employeeSchema)).describe("A list of employees reporting to this employee."),
});

const ai = new GoogleGenAI({});

const prompt = `
Generate an organization chart for a small team.
The manager is Alice, who manages Bob and Charlie. Bob manages David.
`;

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: prompt,
  config: {
    responseFormat: { text: { mimeType: "application/json", schema: zodToJsonSchema(employeeSchema) } },
  },
});

const employee = employeeSchema.parse(JSON.parse(response.text));
console.log(employee);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := `
  Generate an organization chart for a small team.
  The manager is Alice, who manages Bob and Charlie. Bob manages David.
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "name":        map[string]any{"type": "string"},
                "employee_id": map[string]any{"type": "integer"},
                "reports": map[string]any{
                    "type":        "array",
                    "description": "A list of employees reporting to this employee.",
                    "items": map[string]any{
                        "$ref": "#",
                    },
                },
            },
            "required": []string{"name", "employee_id", "reports"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "Generate an organization chart for a small team.\nThe manager is Alice, who manages Bob and Charlie. Bob manages David." }
        ]
      }],
      "generationConfig": {
        "responseFormat": {
          "text": {
            "mimeType": "application/json",
            "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "employee_id": { "type": "integer" },
            "reports": {
              "type": "array",
              "description": "A list of employees reporting to this employee.",
              "items": {
                "$ref": "#"
              }
          }
        }
      }
          },
          "required": ["name", "employee_id", "reports"]
        }
      }
    }'

示例回答：

{
  "name": "Alice",
  "employee_id": 101,
  "reports": [
    {
      "name": "Bob",
      "employee_id": 102,
      "reports": [
        {
          "name": "David",
          "employee_id": 104,
          "reports": []
        }
      ]
    },
    {
      "name": "Charlie",
      "employee_id": 103,
      "reports": []
    }
  ]
}

流式

您可以流式传输结构化输出，这样一来，您就可以在生成回答的同时开始处理回答，而无需等待整个输出完成。这有助于提升应用的感知性能。

流式传输的块将是有效的部分 JSON 字符串，可以连接起来形成最终的完整 JSON 对象。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!"

response_stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents=prompt,
    config={
        "response_format": {"text": {"mime_type": "application/json", "schema": Feedback.model_json_schema()}},
    },
)

for chunk in response_stream:
    print(chunk.candidates[0].content.parts[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});
const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";

const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await ai.models.generateContentStream({
  model: "gemini-3.5-flash",
  contents: prompt,
  config: {
    responseFormat: { text: { mimeType: "application/json", schema: zodToJsonSchema(feedbackSchema) } },
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].text)
}

使用工具生成结构化输出

Gemini 3 可让您将结构化输出与内置工具相结合，包括依托 Google 搜索进行接地、网址上下文、代码执行、文件搜索和函数调用。

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_format": {"text": {"mime_type": "application/json", "schema": MatchResult.model_json_schema()}},
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3.1-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseFormat: { text: { mimeType: "application/json", schema: zodToJsonSchema(matchSchema) } },
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseFormat": {
          "text": {
            "mimeType": "application/json",
            "schema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
          }
        }
      },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

JSON 架构支持

如需生成 JSON 对象，请在生成配置中设置 response_format。该架构必须是描述所需输出格式的有效 JSON 架构。

然后，模型会生成一个语法上有效的 JSON 字符串，该字符串与所提供的架构相符。使用结构化输出时，模型将按架构中键的顺序生成输出。

Gemini 的结构化输出模式支持部分 JSON 架构规范。

支持以下 type 值：

string：对于文本。
number：适用于浮点数。
integer：适用于整数。
boolean：对于 true/false 值。
object：适用于包含键值对的结构化数据。
array：适用于商品列表。
null：如需允许属性为 null，请在类型数组中添加 "null"（例如 {"type": ["string", "null"]}）。

这些描述性属性有助于引导模型：

title：属性的简短说明。
description：属性的更长、更详细的说明。

特定于类型的属性

对于 object 值：

properties：一个对象，其中每个键都是属性名称，每个值都是相应属性的架构。
required：一个字符串数组，列出了哪些属性是必需的。
additionalProperties：控制是否允许使用未在 properties 中列出的属性。可以是布尔值或架构。

对于 string 值：

enum：列出分类任务的一组特定可能字符串。
format：指定字符串的语法，例如 date-time、date、time。

对于 number 和 integer 值：

enum：列出了一组特定的可能数值。
minimum：包含在内的最小值。
maximum：最大值（含）。

对于 array 值：

items：定义数组中所有元素的架构。
prefixItems：为前 N 个项定义架构列表，从而实现类似元组的结构。
minItems：数组中的最小项数。
maxItems：数组中的项数上限。

模型支持

以下模型支持结构化输出：

模型	结构化输出
Gemini 3.1 Flash-Lite	✔️
Gemini 3 Pro 预览版	✔️
Gemini 3.5 Flash	✔️
Gemini 3.1 Flash-Lite 预览版	✔️
Gemini 2.5 Pro	✔️
Gemini 2.5 Flash	✔️
Gemini 2.5 Flash-Lite	✔️
Gemini 2.0 Flash	✔️*
Gemini 2.0 Flash-Lite	✔️*

* 请注意，Gemini 2.0 需要在 JSON 输入中明确指定 propertyOrdering 列表，以定义首选结构。您可以在此实用指南中找到相关示例。

结构化输出与函数调用

结构化输出和函数调用都使用 JSON 架构，但用途不同：

功能	主要使用场景
结构化输出	设置最终用户响应的格式。如果您希望模型的回答采用特定格式（例如，从文档中提取数据以保存到数据库），请使用此参数。
函数调用	在对话期间采取行动。当模型需要要求您执行任务（例如“获取当前天气”）才能提供最终答案时，请使用此选项。

最佳做法

清晰的说明：使用架构中的 description 字段向模型清晰说明每个属性的含义。这对于引导模型的输出至关重要。
强类型：尽可能使用特定类型（integer、string、enum）。如果某个形参的有效值集有限，请使用 enum。
提示工程：在提示中明确说明您希望模型执行的操作。例如，“从文本中提取以下信息…”或“根据提供的架构对这条反馈进行分类…”。
验证：虽然结构化输出可保证 JSON 在语法上正确，但无法保证值在语义上正确。请务必先验证应用代码中的最终输出，然后再使用。
错误处理：在应用中实现强大的错误处理机制，以便妥善管理模型输出（虽然符合架构，但可能不符合业务逻辑要求）的情况。

限制

架构子集：不支持 JSON 架构规范的所有功能。模型会忽略不支持的属性。
架构复杂性：该 API 可能会拒绝非常大或嵌套很深的架构。如果您遇到错误，请尝试缩短属性名称、减少嵌套或限制约束数量，以简化架构。

全文转载：Gemini API 长上下文

Wed, 17 Jun 2026 12:18:00 +0800

原文标题：Gemini API 长上下文

作者/来源：Google AI for Developers / Google AI for Developers

原文链接：https://ai.google.dev/gemini-api/docs/long-context?hl=zh-cn

许可证/授权：Creative Commons Attribution 4.0 / Apache 2.0 for code samples

许多 Gemini 模型都配备了 100 万个或更多 token 的大型上下文窗口。过去，大语言模型 (LLM) 受到一次可传递给模型的文本（或 token）数量的极大限制。Gemini 的长上下文窗口发掘了许多新的应用场景和开发者模式。

您已用于文本生成或多模态输入等场景的代码可以直接用于长上下文，无需进行任何更改。

本文档简要介绍了如何使用上下文窗口包含 100 万个及更多 token 的模型。本页面简要介绍了上下文窗口，并探讨了开发者应如何考虑长上下文、长上下文的各种实际应用场景，以及优化长上下文使用的方法。

如需了解特定模型的上下文窗口大小，请参阅模型页面。

什么是上下文窗口？

使用 Gemini 模型的基本方法是将信息（上下文）传递给模型，模型随后会生成回答。上下文窗口可以比作短期记忆。人们的短期记忆可以存储有限的信息量，生成模型也是如此。

您可以参阅我们的生成模型指南，详细了解模型在后台的工作原理。

开始使用长上下文

早期的生成模型一次只能处理 8,000 个词元。较新的模型进一步提高了此数字，可接受 32,000 个甚至 128,000 个词元。Gemini 是第一个能够接受 100 万个 token 的模型。

在实际中，100 万个词元相当于：

50,000 行代码（标准为每行 80 个字符）
您在过去 5 年内发送的所有短信
8 部平均长度的英语小说
200 多个平均时长播客剧集的转写内容

许多其他模型中常见的上下文窗口较为有限，因此通常需要采用一些策略，例如随意舍弃旧消息、总结内容、将 RAG 与向量数据库搭配使用，或过滤提示以节省 token。

虽然这些技巧在特定场景中仍然很有价值，但 Gemini 庞大的上下文窗口支持更直接的方法：预先提供所有相关信息。由于 Gemini 模型是使用强大的上下文功能专门构建的，因此它们具有强大的上下文学习能力。例如，仅使用上下文中的教学材料（一本 500 页的参考语法书、一本字典和约 400 个平行句子），Gemini 学会了将英语翻译成卡拉芒语（一种使用者不到 200 人的巴布亚语言），翻译质量与使用相同材料的人类学习者相当。这说明了 Gemini 的长上下文所带来的范式转变，通过强大的上下文学习能力开辟了新的可能性。

长上下文应用场景

虽然大多数生成模型的标准应用场景仍然是文本输入，但 Gemini 模型系列可实现多模态应用场景的新模式。这些模型可采用原生方式理解文本、视频、音频和图片。它们附带可接受多模态文件类型的 Gemini API，以方便使用。

长文本

事实证明，文本是支撑 LLM 大部分发展势头的智能层。如前所述，LLM 的很多实际限制是因为没有足够大的上下文窗口来执行某些任务。这导致了检索增强生成 (RAG) 和其他技术的快速采用，这些技术可为模型动态提供相关的上下文信息。现在，随着上下文窗口越来越大，出现了一些新技术可用于发掘新的应用场景。

基于文本的长上下文的一些新兴和标准应用场景包括：

总结大型文本语料库
- 之前使用较小上下文模型的总结方法需要使用滑动窗口或其他技术，以便在新词元传递给模型时保留之前部分的状态
问答
- 过去在上下文数量有限且模型的真实召回率较低的情况下，只有使用 RAG 才能实现这一目的
智能体工作流
- 文本是智能体如何保存已完成的操作和需要执行的操作的状态的基础；如果没有关于实际世界和智能体目标的足够信息，会限制智能体的可靠性

多样本上下文学习是长上下文模型发掘的最独特功能之一。研究表明，采用常见的“单样本”或“多样本”示例模式，在其中向模型提供一个或几个任务示例，然后扩展到多达数百个、数千个甚至数十万个示例，这可能形成全新的模型功能。事实证明，这种多样本方法的性能与针对特定任务进行了微调的模型类似。对于 Gemini 模型的性能尚不足以满足生产发布的应用场景，您可以尝试多样本方法。正如您稍后将在长上下文优化部分中所了解的那样，上下文缓存使这种高输入词元工作负载类型在经济上更加可行，在某些场景中甚至可降低延迟。

长视频

无法访问媒体本身长期以来一直限制着视频内容的实用性。浏览内容并非易事，转写通常无法捕获视频的细微差别，而且大多数工具无法同时处理图片、文本和音频。在 Gemini 中，长上下文文本功能可转换为以持续的性能推理和回答有关多模态输入的问题的能力。

视频长上下文的一些新兴和标准应用场景包括：

视频问答
视频内存，如 Google 的 Project Astra 所示
视频字幕
视频推荐系统，通过新的多模态理解来丰富现有元数据
视频自定义，可查看数据以及关联视频元数据的语料库，然后移除与观看者无关的视频部分
视频内容审核
实时视频处理

处理视频时，重要的是考虑如何将视频处理为词元，这会影响结算和用量限额。如需详细了解如何使用视频文件进行提示，请参阅提示指南。

长音频

Gemini 模型是首批能够理解音频的原生多模态大语言模型。传统上，典型的开发者工作流涉及将多个特定于领域的模型（例如语音转文字模型和文本到文本模型）串联起来，以便处理音频。这会导致执行多次往返请求所需的延迟时间增加并且性能下降，这通常归因于多模型设置的分离架构。

音频上下文的一些新兴和标准应用场景包括：

实时转写和翻译
播客/视频问答
会议转写和总结
语音助理

如需详细了解如何使用音频文件进行提示，请参阅提示指南。

长上下文优化

使用长上下文和 Gemini 模型时，主要优化方法是使用上下文缓存。除了以前无法在单个请求中处理大量词元之外，另一个主要限制是费用。如果您有一个“与数据聊天”应用，用户在其中上传了 10 个 PDF 文件、一个视频和一些工作文档，那么过去您必须使用更复杂的检索增强生成 (RAG) 工具/框架来处理这些请求，并为移入上下文窗口的词元支付大量费用。现在，您可以缓存用户上传的文件，并按小时为存储这些文件付费。例如，使用 Gemini Flash 时，每个请求的输入 / 输出费用比标准输入 / 输出费用低约 4 倍，因此如果用户与其数据进行足够多的聊天，便可为作为开发者的您节省大量费用。

长上下文限制

在本指南的各个部分中，我们讨论了 Gemini 模型如何在各种“大海捞针”检索评估中实现高性能。这些测试考虑了最基本的设置，您在其中只需寻找一根“针”。如果您要寻找多根“针”或特定信息，模型执行的准确率会有所不同。性能可能会因上下文而变化很大。考虑这一点很重要，因为在检索到正确信息与费用之间存在固有的权衡。您在单个查询中可获得大约 99% 的准确率，但每次发送该查询时，您都必须支付输入词元费用。因此，要检索 100 条信息，如果您需要 99% 的性能，则可能需要发送 100 个请求。这是一个很好的示例，上下文缓存在其中可显著降低与使用 Gemini 模型关联的费用，同时保持高性能。

常见问题解答

在上下文窗口中，将查询放在哪个位置效果最好？

在大多数情况下，尤其是当总上下文较长时，如果您将查询 / 问题放在提示的末尾（在所有其他上下文之后），模型的效果会更好。

向查询中添加更多令牌后，模型性能会下降吗？

一般来说，如果您不需要将令牌传递给模型，最好避免传递令牌。不过，如果您有一大块包含某些信息的 token，并且想就这些信息提问，模型能够非常准确地提取这些信息（在许多情况下，准确率高达 99%）。

如何通过长上下文查询降低费用？

如果您有一组类似的 token / 上下文想要多次重复使用，上下文缓存有助于减少与询问该信息相关联的费用。

上下文长度是否会影响模型延迟时间？

无论请求大小如何，任何给定请求都存在一定的固定延迟时间，但一般来说，较长的查询会产生更高的延迟时间（从发出请求到获得第一个令牌的时间）。

全文转载：Gemini API 函数调用

Wed, 17 Jun 2026 12:15:00 +0800

原文标题：Gemini API 函数调用

作者/来源：Google AI for Developers / Google AI for Developers

原文链接：https://ai.google.dev/gemini-api/docs/function-calling?hl=zh-cn

许可证/授权：Creative Commons Attribution 4.0 / Apache 2.0 for code samples

使用 Gemini API 进行函数调用

重要提示：Gemini 3 模型 API 现在会为每个函数调用生成唯一的 id。如果您是手动构建对话历史记录或使用 REST API，建议您在将已执行函数的结果返回给模型时，在 functionResponse 中传递匹配的 id。如果您使用的是标准 Python 或 Node.js SDK，系统会自动处理此问题。

函数调用功能可让您将模型连接到外部工具和 API。模型不会生成文本回答，而是确定何时调用特定函数，并提供执行实际操作所需的参数。这样一来，模型就可以充当自然语言与实际操作和数据之间的桥梁。函数调用功能有 3 个主要使用情形：

执行操作：使用 API 与外部系统互动，例如安排预约、创建账单、发送电子邮件或控制智能家居设备。
扩充知识：从数据库、API 和知识库等外部来源获取信息。
扩展功能：使用外部工具执行计算，并扩展模型的功能限制，例如使用计算器或创建图表。

您可以浏览以下示例，了解这些使用情形：

安排会议

此示例展示了如何定义一个函数，用于在特定时间安排与参会者的会议，从而使模型能够解析用户请求并返回结构化实参，以触发外部系统中的操作。

Python

from google import genai
from google.genai import types

# Define the function declaration for the model
schedule_meeting_function = {
    "name": "schedule_meeting",
    "description": "Schedules a meeting with specified attendees at a given time and date.",
    "parameters": {
        "type": "object",
        "properties": {
            "attendees": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of people attending the meeting.",
            },
            "date": {
                "type": "string",
                "description": "Date of the meeting (e.g., '2024-07-29')",
            },
            "time": {
                "type": "string",
                "description": "Time of the meeting (e.g., '15:00')",
            },
            "topic": {
                "type": "string",
                "description": "The subject or topic of the meeting.",
            },
        },
        "required": ["attendees", "date", "time", "topic"],
    },
}

# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[schedule_meeting_function])
config = types.GenerateContentConfig(tools=[tools])

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning.",
    config=config,
)

# Check for a function call
if response.candidates[0].content.parts[0].function_call:
    function_call = response.candidates[0].content.parts[0].function_call
    print(f"Function to call: {function_call.name}")
    print(f"ID: {function_call.id}")
    print(f"Arguments: {function_call.args}")
    #  In a real app, you would call your function here:
    #  result = schedule_meeting(**function_call.args)
else:
    print("No function call found in the response.")
    print(response.text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

// Configure the client
const ai = new GoogleGenAI({});

// Define the function declaration for the model
const scheduleMeetingFunctionDeclaration = {
  name: 'schedule_meeting',
  description: 'Schedules a meeting with specified attendees at a given time and date.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      attendees: {
        type: Type.ARRAY,
        items: { type: Type.STRING },
        description: 'List of people attending the meeting.',
      },
      date: {
        type: Type.STRING,
        description: 'Date of the meeting (e.g., "2024-07-29")',
      },
      time: {
        type: Type.STRING,
        description: 'Time of the meeting (e.g., "15:00")',
      },
      topic: {
        type: Type.STRING,
        description: 'The subject or topic of the meeting.',
      },
    },
    required: ['attendees', 'date', 'time', 'topic'],
  },
};

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: 'Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about the Q3 planning.',
  config: {
    tools: [{
      functionDeclarations: [scheduleMeetingFunctionDeclaration]
    }],
  },
});

// Check for function calls in the response
if (response.functionCalls && response.functionCalls.length > 0) {
  const functionCall = response.functionCalls[0]; // Assuming one function call
  console.log(`Function to call: ${functionCall.name}`);
  console.log(`ID: ${functionCall.id}`);
  console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
  // In a real app, you would call your actual function here:
  // const result = await scheduleMeeting(functionCall.args);
} else {
  console.log("No function call found in the response.");
  console.log(response.text);
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about the Q3 planning."
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "schedule_meeting",
            "description": "Schedules a meeting with specified attendees at a given time and date.",
            "parameters": {
              "type": "object",
              "properties": {
                "attendees": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of people attending the meeting."
                },
                "date": {
                  "type": "string",
                  "description": "Date of the meeting (e.g., '2024-07-29')"
                },
                "time": {
                  "type": "string",
                  "description": "Time of the meeting (e.g., '15:00')"
                },
                "topic": {
                  "type": "string",
                  "description": "The subject or topic of the meeting."
                }
              },
              "required": ["attendees", "date", "time", "topic"]
            }
          }
        ]
      }
    ]
  }'

获取天气信息

此示例展示了如何定义一个用于检索某个位置的温度数据的函数，从而使模型能够调用外部 API 来回答需要实时信息或外部信息的查询。

Python

from google import genai
from google.genai import types

# Define the function declaration for the model
weather_function = {
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[weather_function])
config = types.GenerateContentConfig(tools=[tools])

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the temperature in London?",
    config=config,
)

# Check for a function call
if response.candidates[0].content.parts[0].function_call:
    function_call = response.candidates[0].content.parts[0].function_call
    print(f"Function to call: {function_call.name}")
    print(f"ID: {function_call.id}")
    print(f"Arguments: {function_call.args}")
    #  In a real app, you would call your function here:
    #  result = get_current_temperature(**function_call.args)
else:
    print("No function call found in the response.")
    print(response.text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

// Configure the client
const ai = new GoogleGenAI({});

// Define the function declaration for the model
const weatherFunctionDeclaration = {
  name: 'get_current_temperature',
  description: 'Gets the current temperature for a given location.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      location: {
        type: Type.STRING,
        description: 'The city name, e.g. San Francisco',
      },
    },
    required: ['location'],
  },
};

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: "What's the temperature in London?",
  config: {
    tools: [{
      functionDeclarations: [weatherFunctionDeclaration]
    }],
  },
});

// Check for function calls in the response
if (response.functionCalls && response.functionCalls.length > 0) {
  const functionCall = response.functionCalls[0]; // Assuming one function call
  console.log(`Function to call: ${functionCall.name}`);
  console.log(`ID: ${functionCall.id}`);
  console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
  // In a real app, you would call your actual function here:
  // const result = await getCurrentTemperature(functionCall.args);
} else {
  console.log("No function call found in the response.");
  console.log(response.text);
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "What'\''s the temperature in London?"
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_current_temperature",
            "description": "Gets the current temperature for a given location.",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "The city name, e.g. San Francisco"
                }
              },
              "required": ["location"]
            }
          }
        ]
      }
    ]
  }'

创建图表

此示例展示了如何定义一个可根据结构化数据生成条形图的函数，演示了模型如何使用外部工具执行计算或创建视觉资源：

Python

import os
from google import genai
from google.genai import types

# Define the function declaration for the model
create_chart_function = {
    "name": "create_bar_chart",
    "description": "Creates a bar chart given a title, labels, and corresponding values.",
    "parameters": {
        "type": "object",
        "properties": {
            "title": {
                "type": "string",
                "description": "The title for the chart.",
            },
            "labels": {
                "type": "array",
                "items": {"type": "string"},
                "description": "List of labels for the data points (e.g., ['Q1', 'Q2', 'Q3']).",
            },
            "values": {
                "type": "array",
                "items": {"type": "number"},
                "description": "List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000]).",
            },
        },
        "required": ["title", "labels", "values"],
    },
}

# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[create_chart_function])
config = types.GenerateContentConfig(tools=[tools])

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Create a bar chart titled 'Quarterly Sales' with data: Q1: 50000, Q2: 75000, Q3: 60000.",
    config=config,
)

# Check for a function call
if response.candidates[0].content.parts[0].function_call:
    function_call = response.candidates[0].content.parts[0].function_call
    print(f"Function to call: {function_call.name}")
    print(f"ID: {function_call.id}")
    print(f"Arguments: {function_call.args}")
    #  In a real app, you would call your function here using a charting library:
    #  result = create_bar_chart(**function_call.args)
else:
    print("No function call found in the response.")
    print(response.text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

// Configure the client
const ai = new GoogleGenAI({});

// Define the function declaration for the model
const createChartFunctionDeclaration = {
  name: 'create_bar_chart',
  description: 'Creates a bar chart given a title, labels, and corresponding values.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      title: {
        type: Type.STRING,
        description: 'The title for the chart.',
      },
      labels: {
        type: Type.ARRAY,
        items: { type: Type.STRING },
        description: 'List of labels for the data points (e.g., ["Q1", "Q2", "Q3"]).',
      },
      values: {
        type: Type.ARRAY,
        items: { type: Type.NUMBER },
        description: 'List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000]).',
      },
    },
    required: ['title', 'labels', 'values'],
  },
};

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: "Create a bar chart titled 'Quarterly Sales' with data: Q1: 50000, Q2: 75000, Q3: 60000.",
  config: {
    tools: [{
      functionDeclarations: [createChartFunctionDeclaration]
    }],
  },
});

// Check for function calls in the response
if (response.functionCalls && response.functionCalls.length > 0) {
  const functionCall = response.functionCalls[0]; // Assuming one function call
  console.log(`Function to call: ${functionCall.name}`);
  console.log(`ID: ${functionCall.id}`);
  console.log(`Arguments: ${JSON.stringify(functionCall.args)}`);
  // In a real app, you would call your actual function here:
  // const result = await createBarChart(functionCall.args);
} else {
  console.log("No function call found in the response.");
  console.log(response.text);
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Create a bar chart titled ''Quarterly Sales'' with data: Q1: 50000, Q2: 75000, Q3: 60000."
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "create_bar_chart",
            "description": "Creates a bar chart given a title, labels, and corresponding values.",
            "parameters": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "description": "The title for the chart."
                },
                "labels": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of labels for the data points (e.g., [''Q1'', ''Q2'', ''Q3''])."
                },
                "values": {
                  "type": "array",
                  "items": {"type": "number"},
                  "description": "List of numerical values corresponding to the labels (e.g., [50000, 75000, 60000])."
                }
              },
              "required": ["title", "labels", "values"]
            }
          }
        ]
      }
    ]
  }'

函数调用的工作原理

函数调用涉及应用、模型和外部函数之间的结构化互动。下面详细介绍了这个流程：

定义函数声明：在应用代码中定义函数声明。函数声明向模型描述函数的名称、参数和用途。
使用函数声明调用 API：将用户提示连同函数声明一起发送给模型。模型会分析请求，并确定函数调用是否有帮助。如果有，模型会返回一个结构化 JSON 对象，其中包含函数名称、实参和一个唯一 id（对于 Gemini 3 模型，API 现在始终会返回此 id^*）。
执行函数代码（您的责任）：模型不会自行执行函数。您的应用有责任处理响应并检查是否存在函数调用。如果
- 是：提取函数的名称、实参和 id，并在应用中执行相应的函数。
- 否：模型已直接针对提示提供文本回答（此流程在示例中不太突出，但也是一种可能的结果）。
创建用户友好的回答：如果执行了函数，请捕获结果并将其发送回模型，确保在后续对话轮次中包含匹配的 id。模型将使用该结果生成最终的、用户友好的回答，其中包含函数调用的信息。

此过程可以重复多次，从而实现复杂的互动和工作流程。该模型还支持在单个轮次中调用多个函数（并行函数调用）、按顺序调用多个函数（组合式函数调用）以及使用内置 Gemini 工具（多工具使用）。

^* 始终映射函数 ID：Gemini 3 现在始终会为每个 functionCall 返回唯一的 id。请在 functionResponse 中包含此确切的 id，以便模型能够准确地将结果映射回原始请求。

第 1 步：定义函数声明

在应用代码中定义一个函数及其声明，以便用户设置灯光值并发出 API 请求。此函数可以调用外部服务或 API。

Python

# Define a function that the model can call to control smart lights
set_light_values_declaration = {
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

# This is the actual function that would be called based on the model's suggestion
def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {"brightness": brightness, "colorTemperature": color_temp}

JavaScript

import { Type } from '@google/genai';

// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

/**

*   Set the brightness and color temperature of a room light. (mock API)
*   @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
*   @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
*   @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
  return {
    brightness: brightness,
    colorTemperature: color_temp
  };
}

第 2 步：使用函数声明调用模型

定义函数声明后，您可以提示模型使用这些声明。模型会分析提示和函数声明，并决定是直接回答还是调用函数。如果调用了函数，响应对象将包含函数调用建议。

Python

from google.genai import types

# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Define user prompt
contents = [
    types.Content(
        role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
    )
]

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=contents,
    config=config,
)

print(response.candidates[0].content.parts[0].function_call)

JavaScript

import { GoogleGenAI } from '@google/genai';

// Generation config with function declaration
const config = {
  tools: [{
    functionDeclarations: [setLightValuesFunctionDeclaration]
  }]
};

// Configure the client
const ai = new GoogleGenAI({});

// Define user prompt
const contents = [
  {
    role: 'user',
    parts: [{ text: 'Turn the lights down to a romantic level' }]
  }
];

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: contents,
  config: config
});

console.log(response.functionCalls[0]);

然后，模型会返回一个 functionCall 对象，该对象采用与 OpenAPI 兼容的架构，用于指定如何调用一个或多个已声明的函数，以便回答用户的问题。

Python

id='8f2b1a3c' args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'

JavaScript

{
  id: '8f2b1a3c',
  name: 'set_light_values',
  args: { brightness: 25, color_temp: 'warm' }
}

第 3 步：执行 set_light_values 函数代码

从模型的响应中提取函数调用详细信息，解析实参，并执行 set_light_values 函数。

Python

# Extract tool call details, it may not be in the first part.
tool_call = response.candidates[0].content.parts[0].function_call

if tool_call.name == "set_light_values":
    result = set_light_values(**tool_call.args)
    print(f"Function execution result: {result}")

JavaScript

// Extract tool call details
const tool_call = response.functionCalls[0]

let result;
if (tool_call.name === 'set_light_values') {
  result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}

第 4 步：根据函数结果创建用户友好的回答，然后再次调用模型

最后，将函数执行结果发送回模型，以便模型将此信息纳入其对用户的最终回答中。

Python

from google import genai
from google.genai import types

# Create a function response part
function_response_part = types.Part.from_function_response(
    name=tool_call.name,
    response={"result": result},
    id=tool_call.id,
)

# Append function call and result of the function execution to contents
contents.append(response.candidates[0].content) # Append the content from the model's response.
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

client = genai.Client()
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

JavaScript

// Create a function response part
const function_response_part = {
  name: tool_call.name,
  response: { result },
  id: tool_call.id
}

// Append function call and result of the function execution to contents
contents.push(response.candidates[0].content);
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

// Get the final response from the model
const final_response = await ai.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

这样就完成了函数调用流程。模型成功使用了 set_light_values 函数来执行用户的请求操作。

函数声明

在提示中实现函数调用时，您需要创建一个 tools 对象，其中包含一个或多个 function declarations。您可以使用 JSON（具体来说是 OpenAPI 架构格式的选定子集）来定义函数。单个函数声明可以包含以下参数：

name（字符串）：函数的唯一名称（get_weather_forecast、send_email）。请使用不含空格或特殊字符的描述性名称（使用下划线或驼峰式命名法）。
description（字符串）：对函数用途和功能的清晰详细说明。这对于模型了解何时使用该函数至关重要。请尽可能具体，并在有帮助的情况下提供示例（“根据位置信息查找影院，还可以选择查找当前正在影院上映的电影。”）。
parameters（对象）：定义函数预期的输入参数。
- type（字符串）：指定总体数据类型，例如 object。
- properties（对象）：列出各个参数，每个参数都具有以下属性：
  - type（字符串）：参数的数据类型，例如 string、integer、boolean, array。
  - description（字符串）：对参数的用途和格式的说明。提供示例和限制条件（例如“城市和州，例如‘加利福尼亚州旧金山’或邮政编码，例如‘95616’。”）。
  - enum（数组，可选）：如果参数值来自固定集，请使用“枚举”列出允许的值，而不是仅在说明中描述这些值。这有助于提高准确率（“枚举”：["daylight", "cool", "warm"]）。
- required（数组）：一个字符串数组，列出了函数运行所必需的参数名称。

您还可以使用 types.FunctionDeclaration.from_callable(client=client, callable=your_function) 直接从 Python 函数构建 FunctionDeclarations。

使用思考模型进行函数调用

Gemini 3 和 2.5 系列模型使用内部“思考”过程来推理请求。这可显著提高函数调用性能，使模型能够更好地确定何时调用函数以及使用哪些参数。由于 Gemini API 是无状态的，因此模型会使用思考特征在多轮对话中保持上下文。

本部分介绍了如何对思维签名进行高级管理，仅在您手动构建 API 请求（例如通过 REST）或操纵对话历史记录时才需要阅读。

如果您使用的是 Google GenAI SDK（我们的官方库），则无需管理此流程。SDK 会自动处理必要的步骤，如之前的示例所示。

手动管理对话记录

如果您手动修改对话历史记录，而不是发送完整的上一个回答，则必须正确处理模型回答中包含的 thought_signature。

请遵循以下规则以确保保留模型的上下文：

始终将 thought_signature 在其原始 Part 内发送回模型。
请务必在 function_response 中包含 function_call 中的确切 id，以便 API 将结果映射到正确的请求。
不要将包含签名的 Part 与不包含签名的部分合并。这会破坏思考的位置上下文。
不要组合两个都包含签名的 Parts，因为签名字符串无法合并。

Gemini 3 思维签名

在 Gemini 3 中，模型回答的任何 Part 都可能包含思考签名。虽然我们通常建议从所有 Part 类型返回签名，但对于函数调用，必须传递思考签名。除非您手动操纵对话历史记录，否则 Google GenAI SDK 会自动处理思考签名。

如果您要手动处理对话记录，请参阅思考签名页面，获取有关处理 Gemini 3 思考签名的完整指南和详细信息。

检查思考签名

虽然不是必需的，但您可以检查响应，以查看 thought_signature，用于调试或学习。

Python

import base64
# After receiving a response from a model with thinking enabled
# response = client.models.generate_content(...)

# The signature is attached to the response part containing the function call
part = response.candidates[0].content.parts[0]
if part.thought_signature:
  print(base64.b64encode(part.thought_signature).decode("utf-8"))

JavaScript

// After receiving a response from a model with thinking enabled
// const response = await ai.models.generateContent(...)

// The signature is attached to the response part containing the function call
const part = response.candidates[0].content.parts[0];
if (part.thoughtSignature) {
  console.log(part.thoughtSignature);
}

如需详细了解思路签名的限制和使用情况，以及一般的思考模型，请参阅思考页面。

并行函数调用

除了单轮函数调用之外，您还可以一次调用多个函数。并行函数调用可让您同时执行多个函数，适用于函数之间没有依赖关系的情况。这在以下场景中非常有用：从多个独立来源收集数据，例如从不同数据库检索客户详细信息、检查各个仓库的库存水平，或执行多项操作，例如将公寓改造成迪斯科舞厅。

当模型在单个对话轮次中发起多次函数调用时，您无需按接收 function_call 对象的顺序返回 function_result 对象。Gemini API 会使用模型输出中的 id 将每个结果映射回其对应的调用。这样，您就可以异步执行函数，并在函数完成时将结果附加到列表中。

Python

power_disco_ball = {
    "name": "power_disco_ball",
    "description": "Powers the spinning disco ball.",
    "parameters": {
        "type": "object",
        "properties": {
            "power": {
                "type": "boolean",
                "description": "Whether to turn the disco ball on or off.",
            }
        },
        "required": ["power"],
    },
}

start_music = {
    "name": "start_music",
    "description": "Play some music matching the specified parameters.",
    "parameters": {
        "type": "object",
        "properties": {
            "energetic": {
                "type": "boolean",
                "description": "Whether the music is energetic or not.",
            },
            "loud": {
                "type": "boolean",
                "description": "Whether the music is loud or not.",
            },
        },
        "required": ["energetic", "loud"],
    },
}

dim_lights = {
    "name": "dim_lights",
    "description": "Dim the lights.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "number",
                "description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
            }
        },
        "required": ["brightness"],
    },
}

JavaScript

import { Type } from '@google/genai';

const powerDiscoBall = {
  name: 'power_disco_ball',
  description: 'Powers the spinning disco ball.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      power: {
        type: Type.BOOLEAN,
        description: 'Whether to turn the disco ball on or off.'
      }
    },
    required: ['power']
  }
};

const startMusic = {
  name: 'start_music',
  description: 'Play some music matching the specified parameters.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      energetic: {
        type: Type.BOOLEAN,
        description: 'Whether the music is energetic or not.'
      },
      loud: {
        type: Type.BOOLEAN,
        description: 'Whether the music is loud or not.'
      }
    },
    required: ['energetic', 'loud']
  }
};

const dimLights = {
  name: 'dim_lights',
  description: 'Dim the lights.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
      }
    },
    required: ['brightness']
  }
};

配置函数调用模式，以允许使用所有指定的工具。如需了解详情，您可以阅读有关配置函数调用的文章。

Python

from google import genai
from google.genai import types

# Configure the client and tools
client = genai.Client()
house_tools = [
    types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]
config = types.GenerateContentConfig(
    tools=house_tools,
    automatic_function_calling=types.AutomaticFunctionCallingConfig(
        disable=True
    ),
    # Force the model to call 'any' function, instead of chatting.
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(mode='ANY')
    ),
)

chat = client.chats.create(model="gemini-3.5-flash", config=config)
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call
print("Example 1: Forced function calling")
for fn in response.function_calls:
    args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
    print(f"{fn.name}({args}) - ID: {fn.id}")

JavaScript

import { GoogleGenAI } from '@google/genai';

// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];

const config = {
    tools: [{
        functionDeclarations: houseFns
    }],
    // Force the model to call 'any' function, instead of chatting.
    toolConfig: {
        functionCallingConfig: {
            mode: 'any'
        }
    }
};

// Configure the client
const ai = new GoogleGenAI({});

// Create a chat session
const chat = ai.chats.create({
    model: 'gemini-3.5-flash',
    config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});

// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
    const args = Object.entries(fn.args)
        .map(([key, val]) => `${key}=${val}`)
        .join(', ');
    console.log(`${fn.name}(${args}) - ID: ${fn.id}`);
}

每个打印结果都反映了模型请求的单个函数调用。如需返回结果，请按请求顺序包含响应。

Python SDK 支持自动函数调用，可自动将 Python 函数转换为声明，并为您处理函数调用执行和响应周期。以下是迪斯科用例的示例。

Python

from google import genai
from google.genai import types

# Actual function implementations
def power_disco_ball_impl(power: bool) -> dict:
    """Powers the spinning disco ball.

    Args:
        power: Whether to turn the disco ball on or off.

    Returns:
        A status dictionary indicating the current state.
    """
    return {"status": f"Disco ball powered {'on' if power else 'off'}"}

def start_music_impl(energetic: bool, loud: bool) -> dict:
    """Play some music matching the specified parameters.

    Args:
        energetic: Whether the music is energetic or not.
        loud: Whether the music is loud or not.

    Returns:
        A dictionary containing the music settings.
    """
    music_type = "energetic" if energetic else "chill"
    volume = "loud" if loud else "quiet"
    return {"music_type": music_type, "volume": volume}

def dim_lights_impl(brightness: float) -> dict:
    """Dim the lights.

    Args:
        brightness: The brightness of the lights, 0.0 is off, 1.0 is full.

    Returns:
        A dictionary containing the new brightness setting.
    """
    return {"brightness": brightness}

# Configure the client
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[power_disco_ball_impl, start_music_impl, dim_lights_impl]
)

# Make the request
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Do everything you need to this place into party!",
    config=config,
)

print("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!

组合式函数调用

组合式或顺序式函数调用可让 Gemini 将多个函数调用链接在一起，以满足复杂的请求。例如，为了回答“获取我当前位置的温度”，Gemini API 可能会先调用 get_current_location() 函数，然后再调用以位置为参数的 get_weather() 函数。

以下示例演示了如何使用 Python SDK 和自动函数调用来实现组合式函数调用。

Python

此示例使用了 google-genai Python SDK 的自动函数调用功能。该 SDK 会自动将 Python 函数转换为所需的架构，在模型请求时执行函数调用，并将结果发送回模型以完成任务。

import os
from google import genai
from google.genai import types

# Example Functions
def get_weather_forecast(location: str) -> dict:
    """Gets the current weather temperature for a given location."""
    print(f"Tool Call: get_weather_forecast(location={location})")
    # TODO: Make API call
    print("Tool Response: {'temperature': 25, 'unit': 'celsius'}")
    return {"temperature": 25, "unit": "celsius"}  # Dummy response

def set_thermostat_temperature(temperature: int) -> dict:
    """Sets the thermostat to a desired temperature."""
    print(f"Tool Call: set_thermostat_temperature(temperature={temperature})")
    # TODO: Interact with a thermostat API
    print("Tool Response: {'status': 'success'}")
    return {"status": "success"}

# Configure the client and model
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[get_weather_forecast, set_thermostat_temperature]
)

# Make the request
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
    config=config,
)

# Print the final, user-facing response
print(response.text)

预期输出

运行代码时，您会看到 SDK 编排函数调用。模型首先调用 get_weather_forecast，接收温度，然后根据提示中的逻辑调用 set_thermostat_temperature 并传入正确的值。

Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. I've set the thermostat to 20°C.

JavaScript

此示例展示了如何使用 JavaScript/TypeScript SDK 通过手动执行循环进行组合式函数调用。

import { GoogleGenAI, Type } from "@google/genai";

// Configure the client
const ai = new GoogleGenAI({});

// Example Functions
function get_weather_forecast({ location }) {
  console.log(`Tool Call: get_weather_forecast(location=${location})`);
  // TODO: Make API call
  console.log("Tool Response: {'temperature': 25, 'unit': 'celsius'}");
  return { temperature: 25, unit: "celsius" };
}

function set_thermostat_temperature({ temperature }) {
  console.log(
    `Tool Call: set_thermostat_temperature(temperature=${temperature})`,
  );
  // TODO: Make API call
  console.log("Tool Response: {'status': 'success'}");
  return { status: "success" };
}

const toolFunctions = {
  get_weather_forecast,
  set_thermostat_temperature,
};

const tools = [
  {
    functionDeclarations: [
      {
        name: "get_weather_forecast",
        description:
          "Gets the current weather temperature for a given location.",
        parameters: {
          type: Type.OBJECT,
          properties: {
            location: {
              type: Type.STRING,
            },
          },
          required: ["location"],
        },
      },
      {
        name: "set_thermostat_temperature",
        description: "Sets the thermostat to a desired temperature.",
        parameters: {
          type: Type.OBJECT,
          properties: {
            temperature: {
              type: Type.NUMBER,
            },
          },
          required: ["temperature"],
        },
      },
    ],
  },
];

// Prompt for the model
let contents = [
  {
    role: "user",
    parts: [
      {
        text: "If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
      },
    ],
  },
];

// Loop until the model has no more function calls to make
while (true) {
  const result = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents,
    config: { tools },
  });

  if (result.functionCalls && result.functionCalls.length > 0) {
    const functionCall = result.functionCalls[0];

    const { name, args } = functionCall;

    if (!toolFunctions[name]) {
      throw new Error(`Unknown function call: ${name}`);
    }

    // Call the function and get the response.
    const toolResponse = toolFunctions[name](args);

    const functionResponsePart = {
      name: functionCall.name,
      response: {
        result: toolResponse,
      },
      id: functionCall.id,
    };

    // Send the function response back to the model.
    contents.push({
      role: "model",
      parts: [
        {
          functionCall: functionCall,
        },
      ],
    });
    contents.push({
      role: "user",
      parts: [
        {
          functionResponse: functionResponsePart,
        },
      ],
    });
  } else {
    // No more function calls, break the loop.
    console.log(result.text);
    break;
  }
}

预期输出

Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. It's 25°C in London, so I've set the thermostat to 20°C.

组合式函数调用是一项原生 Live API 功能。这意味着 Live API 可以像 Python SDK 一样处理函数调用。

Python

# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

JavaScript

// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };

const prompt = `
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;

const tools = [
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];

await run(prompt, tools=tools, modality="AUDIO")

函数调用模式

通过 Gemini API，您可以控制模型使用所提供工具（函数声明）的方式。具体来说，您可以在 .function_calling_config 中设置模式。

VALIDATED：工具组合的默认模式（当内置工具或结构化输出也处于启用状态时）。模型会受限于预测函数调用或自然语言，并确保遵循函数架构。如果未提供 allowed_function_names，模型会从所有可用的函数声明中进行选择。如果提供了 allowed_function_names，模型会从一组允许的函数中进行选择。与 AUTO 模式相比，此模式可减少格式错误的函数调用。
AUTO：仅启用 function_declarations 工具时的默认模式。模型会根据提示和上下文决定是生成自然语言回答还是建议进行函数调用。
ANY：模型会受到限制，始终预测函数调用，并确保符合函数架构。如果未指定 allowed_function_names，模型可以从提供的任何函数声明中进行选择。如果 allowed_function_names 以列表形式提供，模型只能从该列表中的函数中进行选择。如果您需要针对每个提示（如果适用）获得函数调用响应，请使用此模式。
NONE：模型禁止进行函数调用。这相当于发送不含任何函数声明的请求。使用此参数可暂时停用函数调用，而无需移除工具定义。

Python

from google.genai import types

# Configure function calling mode
tool_config = types.ToolConfig(
    function_calling_config=types.FunctionCallingConfig(
        mode="ANY", allowed_function_names=["get_current_temperature"]
    )
)

# Create the generation config
config = types.GenerateContentConfig(
    tools=[tools],  # not defined here.
    tool_config=tool_config,
)

JavaScript

import { FunctionCallingConfigMode } from '@google/genai';

// Configure function calling mode
const toolConfig = {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
    allowedFunctionNames: ['get_current_temperature']
  }
};

// Create the generation config
const config = {
  tools: tools, // not defined here.
  toolConfig: toolConfig,
};

自动函数调用（仅限 Python）

使用 Python SDK 时，您可以直接将 Python 函数作为工具提供。SDK 会将这些函数转换为声明，管理函数调用执行，并为您处理响应周期。使用类型提示和文档字符串定义函数。为获得最佳效果，建议使用 Google 风格的文档字符串。然后，SDK 会自动执行以下操作：

检测模型返回的函数调用响应。
在代码中调用相应的 Python 函数。
将函数的响应发送回模型。
返回模型的最终文本回答。

SDK 目前不会将实参说明解析为生成的函数声明的属性说明槽。而是将整个文档字符串作为顶级函数说明发送。

Python

from google import genai
from google.genai import types

# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

# Configure the client
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[get_current_temperature]
)  # Pass the function itself

# Make the request
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the temperature in Boston?",
    config=config,
)

print(response.text)  # The SDK handles the function call and returns the final text

您可以使用以下方法停用自动函数调用：

Python

config = types.GenerateContentConfig(
    tools=[get_current_temperature],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

自动函数架构声明

该 API 能够描述以下任何类型。允许使用 Pydantic 类型，前提是这些类型上定义的字段也由允许的类型组成。此处不太支持字典类型（例如 dict[str: int]），请勿使用。

Python

AllowedType = (
  int | float | bool | str | list['AllowedType'] | pydantic.BaseModel)

如需查看推断架构的实际效果，您可以使用 from_callable 对其进行转换：

Python

from google import genai
from google.genai import types

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

client = genai.Client()
fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
print(fn_decl.to_json_dict())

多工具使用：将内置工具与函数调用相结合

您可以启用多个工具，在同一请求中将内置工具与函数调用相结合。

借助工具上下文循环功能，Gemini 3 模型可以开箱即用地将内置工具与函数调用相结合。如需了解详情，请参阅结合使用内置工具和函数调用页面。

Python

from google import genai
from google.genai import types

client = genai.Client()

getWeather = {
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What is the northernmost city in the United States? What's the weather like there today?",
    config=types.GenerateContentConfig(
      tools=[
        types.Tool(
          google_search=types.ToolGoogleSearch(),  # Built-in tool
          function_declarations=[getWeather]       # Custom tool
        ),
      ],
      include_server_side_tool_invocations=True
    ),
)

history = [
    types.Content(
        role="user",
        parts=[types.Part(text="What is the northernmost city in the United States? What's the weather like there today?")]
    ),
    response.candidates[0].content,
    types.Content(
        role="user",
        parts=[types.Part(
            function_response=types.FunctionResponse(
                name="getWeather",
                response={"response": "Very cold. 22 degrees Fahrenheit."},
                id=response.candidates[0].content.parts[2].function_call.id
            )
        )]
    )
]

response_2 = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=history,
    config=types.GenerateContentConfig(
      tools=[
        types.Tool(
          google_search=types.ToolGoogleSearch(),
          function_declarations=[getWeather]
        ),
      ],
      include_server_side_tool_invocations=True
    ),
)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    name: "getWeather",
    description: "Get the weather in a given location",
    parameters: {
        type: "OBJECT",
        properties: {
            location: {
                type: "STRING",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

async function run() {
    const model = client.models.generateContent({
        model: "gemini-3.5-flash",
    });

    const tools = [
      { googleSearch: {} },
      { functionDeclarations: [getWeather] }
    ];
    const toolConfig = { includeServerSideToolInvocations: true };

    const result1 = await model.generateContent({
        contents: [{role: "user", parts: [{text: "What is the northernmost city in the United States? What's the weather like there today?"}]}],
        tools: tools,
        toolConfig: toolConfig,
    });

    const response1 = result1.response;
    const functionCallId = response1.candidates[0].content.parts.find(p => p.functionCall)?.functionCall?.id;

    const history = [
        {
            role: "user",
            parts:[{text: "What is the northernmost city in the United States? What's the weather like there today?"}]
        },
        response1.candidates[0].content,
        {
            role: "user",
            parts: [{
                functionResponse: {
                    name: "getWeather",
                    response: {response: "Very cold. 22 degrees Fahrenheit."},
                    id: functionCallId
                }
            }]
        }
    ];

    const result2 = await model.generateContent({
        contents: history,
        tools: tools,
        toolConfig: toolConfig,
    });
}

run();

对于 Gemini 3 系列之前的型号，请使用 Live API。

多模态函数响应

对于 Gemini 3 系列模型，您可以在发送给模型的函数响应部分中添加多模态内容。模型可以在下一轮对话中处理此多模态内容，从而生成更明智的回答。函数响应中的多模态内容支持以下 MIME 类型：

图片：image/png、image/jpeg、image/webp
文档：application/pdf、text/plain

如需在函数响应中包含多模态数据，请将其作为嵌套在 functionResponse 部分内的一个或多个部分。每个多模态部分都必须包含 inlineData。如果您在结构化 response 字段中引用了多模态部分，则该字段必须包含唯一的 displayName。

您还可以使用 JSON 引用格式 {"$ref": "<displayName>"} 从 functionResponse 部分的结构化 response 字段中引用多模态部分。模型在处理响应时，会将引用替换为多模态内容。每个 displayName 只能在结构化 response 字段中引用一次。

以下示例展示了一条消息，其中包含名为 get_image 的函数的 functionResponse，以及一个包含图片数据（带有 displayName: "instrument.jpg"）的嵌套部分。functionResponse 的 response 字段引用了此图片部分：

Python

from google import genai
from google.genai import types

import requests

client = genai.Client()

# This is a manual, two turn multimodal function calling workflow:

# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
  name="get_image",
  description="Retrieves the image file reference for a specific order item.",
  parameters={
      "type": "object",
      "properties": {
          "item_name": {
              "type": "string",
              "description": "The name or description of the item ordered (e.g., 'instrument')."
          }
      },
      "required": ["item_name"],
  },
)
tool_config = types.Tool(function_declarations=[get_image_declaration])

# 2. Send a message that triggers the tool
prompt = "Show me the instrument I ordered last month."
response_1 = client.models.generate_content(
  model="gemini-3.5-flash",
  contents=[prompt],
  config=types.GenerateContentConfig(
      tools=[tool_config],
  )
)

# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")

function_response_data = {
  "image_ref": {"$ref": "instrument.jpg"},
}
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
function_response_multimodal_data = types.FunctionResponsePart(
  inline_data=types.FunctionResponseBlob(
    mime_type="image/jpeg",
    display_name="instrument.jpg",
    data=image_bytes,
  )
)

# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
  types.Content(role="user", parts=[types.Part(text=prompt)]),
  response_1.candidates[0].content,
  types.Content(
    role="user",
    parts=[
        types.Part.from_function_response(
          id=function_call.id,
          name=function_call.name,
          response=function_response_data,
          parts=[function_response_multimodal_data]
        )
    ],
  )
]

response_2 = client.models.generate_content(
  model="gemini-3.5-flash",
  contents=history,
  config=types.GenerateContentConfig(
      tools=[tool_config],
      thinking_config=types.ThinkingConfig(include_thoughts=True)
  ),
)

print(f"\nFinal model response: {response_2.text}")

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// This is a manual, two turn multimodal function calling workflow:
// 1. Define the function tool
const getImageDeclaration = {
  name: 'get_image',
  description: 'Retrieves the image file reference for a specific order item.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      item_name: {
        type: Type.STRING,
        description: "The name or description of the item ordered (e.g., 'instrument').",
      },
    },
    required: ['item_name'],
  },
};

const toolConfig = {
  functionDeclarations: [getImageDeclaration],
};

// 2. Send a message that triggers the tool
const prompt = 'Show me the instrument I ordered last month.';
const response1 = await client.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: prompt,
  config: {
    tools: [toolConfig],
  },
});

// 3. Handle the function call
const functionCall = response1.functionCalls[0];
const requestedItem = functionCall.args.item_name;
console.log(`Model wants to call: ${functionCall.name}`);

// Execute your tool (e.g., call an API)
// (This is a mock response for the example)
console.log(`Calling external tool for: ${requestedItem}`);

const functionResponseData = {
  image_ref: { $ref: 'instrument.jpg' },
};

const imageUrl = "https://goo.gle/instrument-img";
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

const functionResponseMultimodalData = {
  inlineData: {
    mimeType: 'image/jpeg',
    displayName: 'instrument.jpg',
    data: base64ImageData,
  },
};

// 4. Send the tool's result back
// Append this turn's messages to history for a final response.
const history = [
  { role: 'user', parts: [{ text: prompt }] },
  response1.candidates[0].content,
  {
    role: 'user',
    parts: [
      {
        functionResponse: {
          id: functionCall.id,
          name: functionCall.name,
          response: functionResponseData,
          parts: [functionResponseMultimodalData]
        },
      },
    ],
  },
];

const response2 = await client.models.generateContent({
  model: 'gemini-3.5-flash',
  contents: history,
  config: {
    tools: [toolConfig],
    thinkingConfig: { includeThoughts: true },
  },
});

console.log(`\nFinal model response: ${response2.text}`);

REST

IMG_URL="https://goo.gle/instrument-img"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

# Check for macOS
if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      ...,
      {
        "role": "user",
        "parts": [
        {
            "functionResponse": {
              "name": "get_image",
              "id": "UNIQUE_CALL_ID_HERE",
              "response": {
                "image_ref": {
                  "$ref": "instrument.jpg"
                }
              },
              "parts": [
                {
                  "inlineData": {
                    "displayName": "instrument.jpg",
                    "mimeType":"'"$MIME_TYPE"'",
                    "data": "'"$IMAGE_B64"'"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

使用结构化输出进行函数调用

对于 Gemini 3 系列模型，您可以将函数调用与结构化输出搭配使用。这样，模型就可以预测符合特定架构的函数调用或输出。因此，当模型不生成函数调用时，您会收到格式一致的回答。

Model Context Protocol (MCP)

Model Context Protocol (MCP) 是一种开放标准，用于将 AI 应用与外部工具和数据连接起来。MCP 为模型提供了一种通用协议，用于访问上下文，例如函数（工具）、数据源（资源）或预定义的提示。

Gemini SDK 内置了对 MCP 的支持，可减少样板代码，并为 MCP 工具提供自动工具调用。当模型生成 MCP 工具调用时，Python 和 JavaScript 客户端 SDK 可以自动执行 MCP 工具，并在后续请求中将响应发送回模型，从而继续此循环，直到模型不再进行工具调用。

在此处，您可以找到一个示例，了解如何将本地 MCP 服务器与 Gemini 和 mcp SDK 搭配使用。

Python

确保在所选平台上安装了最新版本的 mcp SDK。

pip install mcp

import os
import asyncio
from datetime import datetime
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

client = genai.Client()

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="npx",  # Executable
    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
    env=None,  # Optional environment variables
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Prompt to get the weather for the current day in London.
            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"

            # Initialize the connection between client and server
            await session.initialize()

            # Send request to the model with MCP function declarations
            response = await client.aio.models.generate_content(
                model="gemini-3.5-flash",
                contents=prompt,
                config=genai.types.GenerateContentConfig(
                    temperature=0,
                    tools=[session],  # uses the session, will automatically call the tool
                    # Uncomment if you **don't** want the SDK to automatically call the tool
                    # automatic_function_calling=genai.types.AutomaticFunctionCallingConfig(
                    #     disable=True
                    # ),
                ),
            )
            print(response.text)

# Start the asyncio event loop and run the main function
asyncio.run(run())

JavaScript

确保您选择的平台上安装了最新版本的 mcp SDK。

npm install @modelcontextprotocol/sdk

import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create server parameters for stdio connection
const serverParams = new StdioClientTransport({
  command: "npx", // Executable
  args: ["-y", "@philschmid/weather-mcp"] // MCP Server
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

// Configure the client
const ai = new GoogleGenAI({});

// Initialize the connection between client and server
await client.connect(serverParams);

// Send request to the model with MCP tools
const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
  config: {
    tools: [mcpToTool(client)],  // uses the session, will automatically call the tool
    // Uncomment if you **don't** want the sdk to automatically call the tool
    // automaticFunctionCalling: {
    //   disable: true,
    // },
  },
});
console.log(response.text)

// Close the connection
await client.close();

内置 MCP 支持的限制

内置 MCP 支持是我们 SDK 中的一项实验性功能，具有以下限制：

仅支持工具，不支持资源和提示
适用于 Python 和 JavaScript/TypeScript SDK。
未来版本可能会出现重大变更。

如果这些限制影响了您构建的内容，您可以随时选择手动集成 MCP 服务器。

支持的模型

本部分列出了模型及其函数调用功能。不包括实验性模型。您可以在模型概览页面上找到全面的功能概览。

模型	函数调用	并行函数调用	组合式函数调用
Gemini 3.1 Pro 预览版	✔️	✔️	✔️
Gemini 3.1 Flash-Lite	✔️	✔️	✔️
Gemini 3.5 Flash	✔️	✔️	✔️
Gemini 2.5 Pro	✔️	✔️	✔️
Gemini 2.5 Flash	✔️	✔️	✔️
Gemini 2.5 Flash-Lite	✔️	✔️	✔️

最佳做法

函数和参数说明：说明应非常清晰且具体。模型会根据这些信息选择正确的函数并提供适当的实参。
命名：使用描述性函数名称（不含空格、英文句点或英文短划线）。
强类型：为参数使用特定类型（整数、字符串、枚举），以减少错误。如果某个形参的有效值集有限，请使用枚举。
工具选择：虽然模型可以使用任意数量的工具，但提供的工具过多可能会增加选择错误或次优工具的风险。为获得最佳结果，请尽量仅提供与上下文或任务相关的工具，最好将有效工具集保持在 10-20 个以内。如果您有大量工具，请考虑根据对话上下文动态选择工具。
提示工程：
- 提供背景信息：告知模型其角色（例如，“你是一位乐于助人的天气助理。”）。
- 提供指令：指定如何以及何时使用函数（例如，“不要猜测日期；始终使用未来日期进行预测。”）。
- 鼓励澄清：指示模型在需要时提出澄清性问题。
- 如需了解有关设计这些提示的更多策略，请参阅智能体工作流。以下是经过测试的系统指令示例。
温度：使用较低的温度（例如 0）可获得更具确定性和可靠性的函数调用。

`temperature`、`top_p` 和 `top_k` 参数控制着模型生成回答的方式。虽然您可以修改这些参数，但我们强烈建议您将 Gemini 3.x 模型的这些参数保留为默认值。更改这些参数（例如将温度设置为低于 1.0）可能会导致意外行为（例如循环或性能下降），尤其是在复杂的数学或推理任务中。
验证：如果函数调用会产生重大后果（例如下单），请在执行之前先向用户验证该调用。
检查完成原因：始终检查模型回答中的 finishReason，以处理模型未能生成有效函数调用的情况。
错误处理：在函数中实现稳健的错误处理机制，以妥善处理意外输入或 API 故障。返回信息丰富的错误消息，供模型用来生成对用户的实用回答。
安全性：调用外部 API 时，请注意安全性。使用适当的身份验证和授权机制。避免在函数调用中公开敏感数据。
令牌限制：函数说明和参数会计入输入令牌限制。如果您遇到 token 限制，请考虑限制函数数量或说明长度，将复杂的任务分解为更小、更集中的函数集。
混合使用 Bash 和自定义工具 对于混合使用 Bash 和自定义工具的开发者，Gemini 3.1 Pro 预览版提供了一个单独的端点，可通过 API 调用 gemini-3.1-pro-preview-customtools 来使用。

注释和限制

函数调用部分的定位：当将自定义函数声明与内置工具（例如 Google 搜索）搭配使用时，模型可能会在单个对话轮次中返回 functionCall、toolCall 和 toolResponse 部分的混合结果。因此，请勿假定 functionCall 始终是 parts 数组中的最后一项。如果您要手动解析 JSON 响应，请务必遍历 parts 数组，而不是依赖于位置。
仅支持 OpenAPI 架构的一部分。
对于 ANY 模式，API 可能会拒绝非常大或嵌套很深的架构。如果您遇到错误，请尝试通过缩短属性名称、减少嵌套或限制函数声明的数量来简化函数参数和响应架构。
Python 中支持的形参类型有限。
自动函数调用仅为 Python SDK 功能。

全文转载：Gemini API 文本生成

Wed, 17 Jun 2026 12:12:00 +0800

原文标题：Gemini API 文本生成

作者/来源：Google AI for Developers / Google AI for Developers

原文链接：https://ai.google.dev/gemini-api/docs/text-generation?hl=zh-cn

许可证/授权：Creative Commons Attribution 4.0 / Apache 2.0 for code samples

文本生成

Gemini API 可以根据文本、图片、视频和音频输入生成文本输出。

下面是一个基本示例：

Python

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="How does AI work?"
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "How does AI work?",
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.5-flash",
      genai.Text("Explain how AI works in a few words"),
      nil,
  )

  fmt.Println(result.Text())
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateContentWithTextInput {
  public static void main(String[] args) {

    Client client = new Client();

    GenerateContentResponse response =
        client.models.generateContent("gemini-3.5-flash", "How does AI work?", null);

    System.out.println(response.text());
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "How does AI work?"
          }
        ]
      }
    ]
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const payload = {
    contents: [
      {
        parts: [
          { text: 'How AI does work?' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

与 Gemini 一起思考

Gemini 模型通常默认启用“思考”功能，以便模型在回答请求之前进行推理。

每种模型都支持不同的思考配置，让您可以控制费用、延迟时间和智能程度。如需了解详情，请参阅思维指南。

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="How does AI work?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

JavaScript

import { GoogleGenAI, ThinkingLevel } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "How does AI work?",
    config: {
      thinkingConfig: {
        thinkingLevel: ThinkingLevel.LOW,
      },
    }
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingLevelVal := "low"

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.5-flash",
      genai.Text("How does AI work?"),
      &genai.GenerateContentConfig{
        ThinkingConfig: &genai.ThinkingConfig{
            ThinkingLevel: &thinkingLevelVal,
        },
      }
  )

  fmt.Println(result.Text())
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.ThinkingConfig;
import com.google.genai.types.ThinkingLevel;

public class GenerateContentWithThinkingConfig {
  public static void main(String[] args) {

    Client client = new Client();

    GenerateContentConfig config =
        GenerateContentConfig.builder()
            .thinkingConfig(ThinkingConfig.builder().thinkingLevel(new ThinkingLevel("low")))
            .build();

    GenerateContentResponse response =
        client.models.generateContent("gemini-3.5-flash", "How does AI work?", config);

    System.out.println(response.text());
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "How does AI work?"
          }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "low"
      }
    }
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const payload = {
    contents: [
      {
        parts: [
          { text: 'How AI does work?' },
        ],
      },
    ],
    generationConfig: {
      thinkingConfig: {
        thinkingLevel: 'low'
      }
    }
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

系统指令和其他配置

您可以使用系统指令来引导 Gemini 模型的行为。为此，请传递一个 GenerateContentConfig 对象。

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="You are a cat. Your name is Neko."),
    contents="Hello there"
)

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Hello there",
    config: {
      systemInstruction: "You are a cat. Your name is Neko.",
    },
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  config := &genai.GenerateContentConfig{
      SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.5-flash",
      genai.Text("Hello there"),
      config,
  )

  fmt.Println(result.Text())
}

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;

public class GenerateContentWithSystemInstruction {
  public static void main(String[] args) {

    Client client = new Client();

    GenerateContentConfig config =
        GenerateContentConfig.builder()
            .systemInstruction(
                Content.fromParts(Part.fromText("You are a cat. Your name is Neko.")))
            .build();

    GenerateContentResponse response =
        client.models.generateContent("gemini-3.5-flash", "Hello there", config);

    System.out.println(response.text());
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "system_instruction": {
      "parts": [
        {
          "text": "You are a cat. Your name is Neko."
        }
      ]
    },
    "contents": [
      {
        "parts": [
          {
            "text": "Hello there"
          }
        ]
      }
    ]
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const systemInstruction = {
    parts: [{
      text: 'You are a cat. Your name is Neko.'
    }]
  };

  const payload = {
    systemInstruction,
    contents: [
      {
        parts: [
          { text: 'Hello there' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

您还可以使用 GenerateContentConfig 对象替换默认生成参数，例如 max_output_tokens。

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=["Explain how AI works"],
    config=types.GenerateContentConfig(
        max_output_tokens=1000
    )
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works",
    config: {
      maxOutputTokens: 1000,
    },
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  config := &genai.GenerateContentConfig{
    MaxOutputTokens:   1000,
    ResponseMIMEType:  "application/json",
  }

  result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.5-flash",
    genai.Text("What is the average size of a swallow?"),
    config,
  )

  fmt.Println(result.Text())
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;

public class GenerateContentWithConfig {
  public static void main(String[] args) {

    Client client = new Client();

    GenerateContentConfig config = GenerateContentConfig.builder().maxOutputTokens(1000).build();

    GenerateContentResponse response =
        client.models.generateContent("gemini-3.5-flash", "Explain how AI works", config);

    System.out.println(response.text());
  }
}

REST

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works"
          }
        ]
      }
    ],
    "generationConfig": {
      "stopSequences": [
        "Title"
      ],
      "maxOutputTokens": 1000
    }
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const generationConfig = {
    maxOutputTokens: 1000,
    responseFormat: { text: { mimeType: "text/plain" } },
  };

  const payload = {
    generationConfig,
    contents: [
      {
        parts: [
          { text: 'Explain how AI works in a few words' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

如需查看可配置参数及其说明的完整列表，请参阅 API 参考文档中的 GenerateContentConfig。

多模态输入

Gemini API 支持多模态输入，让您可以将文本与媒体文件相结合。以下示例演示了如何提供图片：

Python

from PIL import Image
from google import genai

client = genai.Client()

image = Image.open("/path/to/organ.png")
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[image, "Tell me about this instrument"]
)
print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const image = await ai.files.upload({
    file: "/path/to/organ.png",
  });
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
      createUserContent([
        "Tell me about this instrument",
        createPartFromUri(image.uri, image.mimeType),
      ]),
    ],
  });
  console.log(response.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  imagePath := "/path/to/organ.jpg"
  imgData, _ := os.ReadFile(imagePath)

  parts := []*genai.Part{
      genai.NewPartFromText("Tell me about this instrument"),
      &genai.Part{
          InlineData: &genai.Blob{
              MIMEType: "image/jpeg",
              Data:     imgData,
          },
      },
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

Java

import com.google.genai.Client;
import com.google.genai.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Part;

public class GenerateContentWithMultiModalInputs {
  public static void main(String[] args) {

    Client client = new Client();

    Content content =
      Content.fromParts(
          Part.fromText("Tell me about this instrument"),
          Part.fromUri("/path/to/organ.jpg", "image/jpeg"));

    GenerateContentResponse response =
        client.models.generateContent("gemini-3.5-flash", content, null);

    System.out.println(response.text());
  }
}

REST

# Use a temporary file to hold the base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# Use a temporary file to hold the JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
  "contents": [
    {
      "parts": [
        {
          "text": "Tell me about this instrument"
        },
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "$(cat "$TEMP_B64")"
          }
        }
      ]
    }
  ]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d "@$TEMP_JSON"

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const imageUrl = 'http://image/url';
  const image = getImageData(imageUrl);
  const payload = {
    contents: [
      {
        parts: [
          { image },
          { text: 'Tell me about this instrument' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

function getImageData(url) {
  const blob = UrlFetchApp.fetch(url).getBlob();

  return {
    mimeType: blob.getContentType(),
    data: Utilities.base64Encode(blob.getBytes())
  };
}

如需了解提供图片的其他方法和更高级的图片处理功能，请参阅我们的图片理解指南。该 API 还支持文档、视频和音频输入和理解。

流式响应

默认情况下，模型仅在整个生成过程完成后才返回回答。

为了获得更流畅的互动体验，请使用流式传输来逐步接收 GenerateContentResponse 实例（在生成时）。

Python

from google import genai

client = genai.Client()

response = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents=["Explain how AI works"]
)
for chunk in response:
    print(chunk.text, end="")

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContentStream({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works",
  });

  for await (const chunk of response) {
    console.log(chunk.text);
  }
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  stream := client.Models.GenerateContentStream(
      ctx,
      "gemini-3.5-flash",
      genai.Text("Write a story about a magic backpack."),
      nil,
  )

  for chunk, _ := range stream {
      part := chunk.Candidates[0].Content.Parts[0]
      fmt.Print(part.Text)
  }
}

Java

import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

public class GenerateContentStream {
  public static void main(String[] args) {

    Client client = new Client();

    ResponseStream<GenerateContentResponse> responseStream =
      client.models.generateContentStream(
          "gemini-3.5-flash", "Write a story about a magic backpack.", null);

    for (GenerateContentResponse res : responseStream) {
      System.out.print(res.text());
    }

    // To save resources and avoid connection leaks, it is recommended to close the response
    // stream after consumption (or using try block to get the response stream).
    responseStream.close();
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works"
          }
        ]
      }
    ]
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const payload = {
    contents: [
      {
        parts: [
          { text: 'Explain how AI works' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:streamGenerateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

多轮对话（聊天）

我们的 SDK 提供相应功能，可将多轮提示和回答收集到聊天中，让您轻松跟踪对话历史记录。

Python

from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-3.5-flash")

response = chat.send_message("I have 2 dogs in my house.")
print(response.text)

response = chat.send_message("How many paws are in my house?")
print(response.text)

for message in chat.get_history():
    print(f'role - {message.role}',end=": ")
    print(message.parts[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const chat = ai.chats.create({
    model: "gemini-3.5-flash",
    history: [
      {
        role: "user",
        parts: [{ text: "Hello" }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
  });

  const response1 = await chat.sendMessage({
    message: "I have 2 dogs in my house.",
  });
  console.log("Chat response 1:", response1.text);

  const response2 = await chat.sendMessage({
    message: "How many paws are in my house?",
  });
  console.log("Chat response 2:", response2.text);
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  history := []*genai.Content{
      genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser),
      genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
  }

  chat, _ := client.Chats.Create(ctx, "gemini-3.5-flash", nil, history)
  res, _ := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})

  if len(res.Candidates) > 0 {
      fmt.Println(res.Candidates[0].Content.Parts[0].Text)
  }
}

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;

public class MultiTurnConversation {
  public static void main(String[] args) {

    Client client = new Client();
    Chat chatSession = client.chats.create("gemini-3.5-flash");

    GenerateContentResponse response =
        chatSession.sendMessage("I have 2 dogs in my house.");
    System.out.println("First response: " + response.text());

    response = chatSession.sendMessage("How many paws are in my house?");
    System.out.println("Second response: " + response.text());

    // Get the history of the chat session.
    // Passing 'true' to getHistory() returns the curated history, which excludes
    // empty or invalid parts.
    // Passing 'false' here would return the comprehensive history, including
    // empty or invalid parts.
    ImmutableList<Content> history = chatSession.getHistory(true);
    System.out.println("History: " + history);
  }
}

REST

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Hello"
          }
        ]
      },
      {
        "role": "model",
        "parts": [
          {
            "text": "Great to meet you. What would you like to know?"
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "I have two dogs in my house. How many paws are in my house?"
          }
        ]
      }
    ]
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const payload = {
    contents: [
      {
        role: 'user',
        parts: [
          { text: 'Hello' },
        ],
      },
      {
        role: 'model',
        parts: [
          { text: 'Great to meet you. What would you like to know?' },
        ],
      },
      {
        role: 'user',
        parts: [
          { text: 'I have two dogs in my house. How many paws are in my house?' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

流式传输还可用于多轮对话。

Python

from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-3.5-flash")

response = chat.send_message_stream("I have 2 dogs in my house.")
for chunk in response:
    print(chunk.text, end="")

response = chat.send_message_stream("How many paws are in my house?")
for chunk in response:
    print(chunk.text, end="")

for message in chat.get_history():
    print(f'role - {message.role}', end=": ")
    print(message.parts[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const chat = ai.chats.create({
    model: "gemini-3.5-flash",
    history: [
      {
        role: "user",
        parts: [{ text: "Hello" }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
  });

  const stream1 = await chat.sendMessageStream({
    message: "I have 2 dogs in my house.",
  });
  for await (const chunk of stream1) {
    console.log(chunk.text);
    console.log("_".repeat(80));
  }

  const stream2 = await chat.sendMessageStream({
    message: "How many paws are in my house?",
  });
  for await (const chunk of stream2) {
    console.log(chunk.text);
    console.log("_".repeat(80));
  }
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {

  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  history := []*genai.Content{
      genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser),
      genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
  }

  chat, _ := client.Chats.Create(ctx, "gemini-3.5-flash", nil, history)
  stream := chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"})

  for chunk, _ := range stream {
      part := chunk.Candidates[0].Content.Parts[0]
      fmt.Print(part.Text)
  }
}

Java

import com.google.genai.Chat;
import com.google.genai.Client;
import com.google.genai.ResponseStream;
import com.google.genai.types.GenerateContentResponse;

public class MultiTurnConversationWithStreaming {
  public static void main(String[] args) {

    Client client = new Client();
    Chat chatSession = client.chats.create("gemini-3.5-flash");

    ResponseStream<GenerateContentResponse> responseStream =
        chatSession.sendMessageStream("I have 2 dogs in my house.", null);

    for (GenerateContentResponse response : responseStream) {
      System.out.print(response.text());
    }

    responseStream = chatSession.sendMessageStream("How many paws are in my house?", null);

    for (GenerateContentResponse response : responseStream) {
      System.out.print(response.text());
    }

    // Get the history of the chat session. History is added after the stream
    // is consumed and includes the aggregated response from the stream.
    System.out.println("History: " + chatSession.getHistory(false));
  }
}

REST

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Hello"
          }
        ]
      },
      {
        "role": "model",
        "parts": [
          {
            "text": "Great to meet you. What would you like to know?"
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "I have two dogs in my house. How many paws are in my house?"
          }
        ]
      }
    ]
  }'

Apps 脚本

// See https://developers.google.com/apps-script/guides/properties
// for instructions on how to set the API key.
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');

function main() {
  const payload = {
    contents: [
      {
        role: 'user',
        parts: [
          { text: 'Hello' },
        ],
      },
      {
        role: 'model',
        parts: [
          { text: 'Great to meet you. What would you like to know?' },
        ],
      },
      {
        role: 'user',
        parts: [
          { text: 'I have two dogs in my house. How many paws are in my house?' },
        ],
      },
    ],
  };

  const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:streamGenerateContent';
  const options = {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      'x-goog-api-key': apiKey,
    },
    payload: JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response);
  const content = data['candidates'][0]['content']['parts'][0]['text'];
  console.log(content);
}

撰写提示的技巧！

如需了解如何充分利用 Gemini，请参阅我们的提示工程指南。

后续步骤

在 Google AI Studio 中试用 Gemini。
尝试使用结构化输出来生成类似 JSON 的回答。
探索 Gemini 的图片、视频、音频和文档理解功能。
了解多模态文件提示策略。

全文转载：Jetpack Compose 自适应应用入门

Wed, 17 Jun 2026 12:09:00 +0800

原文标题：Jetpack Compose 自适应应用入门

作者/来源：Android Developers / Android Developers

原文链接：https://developer.android.com/develop/ui/compose/layouts/adaptive?hl=zh-cn

许可证/授权：Android Developers Content License

转载声明：本文完整转载自 Android Developers 官方中文文档，页面内容和代码示例受 Android Developers 内容许可约束。本站转载仅用于技术学习与资料归档，已注明作者/来源与原文链接。如有侵权或不希望转载，请联系删除。

如今，Android 大屏设备（包括平板电脑、可折叠设备、ChromeOS 设备、车载显示屏和电视）的使用量已超过 3 亿部，并且还在不断增加。为了在不断增加且种类繁多的大屏设备以及标准手机上提供最佳用户体验，请构建自适应应用。

什么是自适应应用？

自适应应用会根据应用显示的变化（主要是应用窗口的大小）来更改布局。不过，自适应应用还能适应可折叠设备折叠状态的变化（例如桌面折叠状态或图书折叠状态），以及屏幕密度和字体大小的变化。

自适应应用不会仅仅通过拉伸或缩小界面元素来响应不同的窗口大小，而是会替换布局组件并显示或隐藏内容。例如，在标准手机上，自适应应用可能会显示底部导航栏，但在大屏设备上，则会显示侧边导航栏。在大型屏幕上，自适应应用会显示更多内容，例如双窗格的列表-详情布局；在小型屏幕上，则会显示较少内容，即列表或详情。

您的浏览器不支持视频标记。

图 1. 自适应应用可针对不同的窗口大小优化布局。

过去，应用通常以全屏模式运行。如今，应用可以在任意大小的窗口中以多窗口模式运行，不受设备屏幕尺寸的限制。用户可以随时更改窗口大小。因此，即使在单一设备类型上，应用也必须具有自适应性。

自适应应用在任何配置的任何设备上都能呈现出色的外观和运行效果。

为什么要构建自适应界面？

用户希望您的应用在他们的所有设备上都能顺畅运行，并在大屏设备上提供增强的功能。用户可以在多窗口模式下执行多项任务，从而获得更出色的应用体验并提高工作效率。

如果应用在标准手机上只能执行单项任务，那么将错失不断壮大的用户群，以及各种各样的可能性。

Google Play

Google Play 提供平板电脑和可折叠设备专用应用合集和推荐，让用户能够发现高品质应用。

Play 会将针对大屏设备优化的应用和游戏排在未优化的应用前面。Play 会根据大屏设备应用质量指南对应用进行排名。排名越高，应用就越容易被发现，因为多设备用户可以在手机上看到针对大屏幕设备的评分和评价。

如果应用不符合 Play 商店的大屏设备质量标准，系统会在应用详情页面上显示警告。该警告会告知用户，相应应用可能无法在大屏设备上正常运行。

图 2. 应用详情页面上的技术质量警告。

构建自适应应用，以提高在 Google Play 上的曝光度，并最大限度地增加可下载您应用的设备数量。

如何开始

在应用开发的各个阶段（从规划到部署）都应考虑自适应设计。向平面设计师介绍自适应设计。将应用设计为自适应应用，您将构建出易于管理、可扩展且可适应未来设备类型和窗口模式的应用。

如需创建支持所有显示大小和配置的自适应应用，请执行以下操作：

使用窗口大小类做出布局决策
使用 Compose Material 3 自适应库进行构建
支持触控以外的输入方式
在所有设备类型上进行测试

窗口大小类别

即使应用处于全屏模式，应用窗口尺寸在不同设备上（或在可折叠设备上）也可能不同。不同的设备屏幕方向会产生不同的宽高比。在多窗口模式下，应用窗口的大小、宽高比和屏幕方向可能与设备屏幕的不同。

自适应应用在渲染布局时仅考虑应用窗口，从而简化并概括了确定和管理窗口大小、宽高比和屏幕方向的问题，即使应用窗口占满整个屏幕，这种方式也适用。

窗口大小类别可根据窗口宽度或高度将应用窗口分类为紧凑、中等或展开。

图 3. 基于显示宽度的窗口大小类别。

使用 Compose Material 3 Adaptive 库的 currentWindowAdaptiveInfo() 顶级函数计算应用的 WindowSizeClass。该函数会返回一个 WindowAdaptiveInfo 实例，其中包含 windowSizeClass。每当窗口大小类别发生变化时，应用都会收到更新：

val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClassAdaptiveLayoutSnippets.kt

内容窗格

Activity 的布局有时称为“界面”。例如，您的应用可能包含主屏幕、列表界面和商品详情界面。此术语表示每个 activity 都会填满设备屏幕。

不过，在足够大的设备屏幕上，可以支持展开宽度窗口尺寸类，因此多个 activity 屏幕可以同时显示在屏幕上。窗格是用于更精确地指代各个 activity 的内容显示区域的术语。

窗口大小类别可让您确定在多窗格布局中显示多少个内容窗格，如 Material Design 中所指定的那样。

图 4. 每个窗口大小类的内容窗格数量。

窗格可供浏览。在紧凑型和中等窗口大小类中，应用会显示单个窗格；因此，导航到任何目的地都会显示一个窗格。

在展开的窗口大小类别中，应用可以在多个窗格中显示相关内容，例如列表‑详情布局。导航到任一窗格都会显示双窗格布局。如果窗口大小变为紧凑或中等，自适应应用将仅显示一个窗格（即导航目的地），可以是列表或详情。

您的浏览器不支持视频标记。

图 5. 列表-详情布局，其中列表窗格为导航目标。

您的浏览器不支持视频标记。

图 6. 以详情窗格为导航目标的列表-详情布局。

Compose Material 3 自适应

Jetpack Compose 是一种现代声明性方法，可用于构建自适应应用，而无需处理多个布局文件带来的重复和维护负担。

Compose Material 3 自适应库包含用于管理窗口大小类别、导航组件、多窗格布局以及可折叠姿态和铰链位置的可组合项，例如：

NavigationSuiteScaffold：根据应用窗口大小类别和设备姿态，自动在导航栏和侧边导航栏之间切换。
ListDetailPaneScaffold：实现列表-详情规范布局。

使布局适应应用窗口大小。在较大窗口大小类别中，以并排窗格的形式呈现列表和列表项的详细信息；但在较小和中等窗口大小类别中，只呈现列表或详细信息。
SupportingPaneScaffold：实现支持窗格规范布局。

在扩展型窗口大小类别中显示主要内容窗格和辅助窗格，但在紧凑型和中等窗口大小类别中仅显示主要内容窗格。

Compose Material 3 自适应库是开发自适应应用的关键依赖项。

配置和连续性

自适应应用在配置更改期间会保持连续性。

当应用窗口大小调整、可折叠设备的姿态发生变化，或者屏幕密度或字体发生变化时，就会发生配置变更。

默认情况下，配置更改会重新创建应用 activity，并且所有 activity 状态都会丢失。为保持连续性，自适应应用会在 activity 的 onSaveInstanceState() 方法或 ViewModel 中保存状态。

安全状况

自适应应用可以响应可折叠设备折叠状态的变化。姿态包括桌面姿态和图书姿态。

图 7. 处于桌面折叠状态的可折叠设备。

借助 Jetpack WindowManager 中的 WindowInfoTracker 接口，您可以获取设备的 DisplayFeature 对象列表。显示功能包括 FoldingFeature.State，用于指示设备是完全打开还是半打开。

Compose Material 3 Adaptive 库提供 currentWindowAdaptiveInfo() 顶级函数，该函数会返回一个包含 windowPosture 的 WindowAdaptiveInfo 实例。

触控以外的输入方式

用户通常会将外接键盘、触控板、鼠标和触控笔连接到大屏设备。这些外围设备可提高用户的工作效率、输入精确度、个人表达能力和无障碍功能。大多数 ChromeOS 设备都内置了键盘和触控板。

自适应应用支持外部输入设备，但 Android 框架会为您完成大部分工作：

Jetpack Compose 1.7 及更高版本：默认支持键盘标签页导航以及鼠标或触控板点击、选择和滚动。
Jetpack androidx.compose.material3 库：使用户能够使用触控笔在任何 TextField 组件中书写。
键盘快捷键辅助工具：让用户可以发现 Android 平台和应用键盘快捷键。通过替换 onProvideKeyboardShortcuts() 窗口回调，在键盘快捷键帮助程序中发布应用的键盘快捷键。

为了全面支持各种尺寸的设备，自适应应用支持所有类型的输入。

如何测试自适应应用

测试不同的屏幕和窗口尺寸以及不同的设备配置。使用宿主端屏幕截图和 Compose 预览来检查应用布局。在 Android Studio 模拟器和 Google 数据中心内托管的远程 Android 设备上运行应用。

大屏设备应用质量指南

借助大屏设备应用质量指南，您可以验证自适应应用在平板电脑、可折叠设备和 ChromeOS 设备上是否能正常运行。该指南包含一些测试，可让您验证关键用户历程的应用功能。虽然这些指南侧重于大屏幕，但它们与所有屏幕尺寸兼容。

多个配置

Compose 1.7 及更高版本中的 DeviceConfigurationOverride 接口可让您替换设备配置的各个方面。该 API 以本地化的方式模拟不同的设备配置，以便测试您所需的任何可组合内容。例如，您可以在单个设备或模拟器上运行测试套件，一次性测试多个任意界面尺寸。

借助 DeviceConfigurationOverride.then() 扩展函数，您可以同时测试多个配置参数，例如字体大小、语言区域、主题和布局大小。

主机端屏幕截图

主机端截屏测试是一种快速且可扩缩的方式，用于验证应用布局的视觉外观。使用主机端屏幕截图测试界面在各种显示尺寸下的效果。

如需了解详情，请参阅 Compose 预览版屏幕截图测试。

Compose 预览

借助 Compose 预览，您可以在 Android Studio 的设计视图中查看应用的界面。预览使用 @PreviewScreenSizes、@PreviewFontScale 和 @PreviewLightDark 等注释，让您能够以各种配置查看可组合项内容。您甚至可以与预览互动。

Android Studio 还会在预览中突出显示常见的易用性问题，例如过宽的按钮或文本字段。

如需了解详情，请参阅使用可组合项预览功能预览界面。

模拟器

Android Studio 提供了各种模拟器，可用于测试不同的布局尺寸：

可调整大小的模拟器：可模拟手机、平板电脑或可折叠设备，并让您在这些设备之间即时切换
Pixel Fold 模拟器：模拟 Pixel Fold 大屏可折叠手机
Pixel Tablet 模拟器：模拟 Pixel Tablet 大屏设备
桌面模拟器：可用于测试自由调整窗口大小、鼠标悬停和键盘快捷键

远程设备在线播放

安全地连接到 Google 数据中心内托管的远程 Android 设备，并在最新的 Pixel 和 Samsung 设备上运行您的应用。安装和调试应用、运行 ADB 命令，以及旋转和折叠设备，以验证应用在各种真机设备上都能正常运行。

远程设备串流功能已集成到 Android Studio 中。如需了解详情，请参阅由 Firebase 提供支持的 Android 设备串流。

其他资源

I/O 大会演讲：构建自适应 Android 应用

设置商品行为

应用屏幕方向、宽高比和尺寸调整

全文转载：Android 17 功能和 API

Wed, 17 Jun 2026 12:06:00 +0800

原文标题：Android 17 功能和 API

作者/来源：Android Developers / Android Developers

原文链接：https://developer.android.com/about/versions/17/features?hl=zh-cn

许可证/授权：Android Developers Content License

Android 17 面向开发者引入了一些出色的新功能和 API。以下各部分总结了这些功能，可帮助您开始使用相关 API。

如需查看新增、修改和移除的 API 的详细列表，请参阅 API 差异报告。如需详细了解新的 API，请访问 Android API 参考文档，新 API 会突出显示以方便查看。

您还应查看平台变更可能会在哪些方面影响您的应用。如需了解详情，请参阅以下页面：

核心功能

Android 17 添加了以下与核心 Android 功能相关的新功能。

新的 ProfilingManager 触发器

Android 17 向 ProfilingManager 添加了多个新的系统触发器，以帮助您收集深入数据来调试性能问题。

新触发器包括：

TRIGGER_TYPE_COLD_START：在应用冷启动期间触发。它在响应中同时提供调用堆栈样本和系统跟踪记录。
TRIGGER_TYPE_OOM：当应用抛出 OutOfMemoryError时触发，并在响应中提供 Java 堆转储。
TRIGGER_TYPE_KILL_EXCESSIVE_CPU_USAGE：当应用因 CPU 使用异常且过高而被终止时触发，并在响应中提供调用堆栈样本。
TRIGGER_TYPE_ANOMALY：检测系统性能异常，例如 binder 调用过多和内存用量过高。

如需了解如何设置系统触发器，请参阅有关基于触发器的性能分析的文档以及有关如何检索和分析性能分析数据的文档。

应用异常的性能分析触发器

Android 17 引入了一项设备端异常检测服务，用于监控资源密集型行为和潜在的兼容性回归。此服务与ProfilingManager集成，可让您的应用接收由特定系统检测到的事件触发的性能分析工件。

使用 TRIGGER_TYPE_ANOMALY 触发器检测系统性能问题例如 binder 调用过多和内存用量过高。当应用违反操作系统定义的内存限制时，异常触发器允许开发者接收特定于应用的堆转储，以帮助识别和修复内存问题。此外，对于 binder 垃圾内容过多，异常触发器会提供有关 binder 事务的堆栈抽样分析报告。

此 API 回调发生在系统强制执行任何操作之前。例如，它可以帮助开发者在应用因超出内存限制而被系统终止之前收集调试数据。

val profilingManager =
    applicationContext.getSystemService(ProfilingManager::class.java)
val triggers = ArrayList<ProfilingTrigger>()
triggers.add(ProfilingTrigger.Builder(ProfilingTrigger.TRIGGER_TYPE_ANOMALY))
val mainExecutor: Executor = Executors.newSingleThreadExecutor()
val resultCallback = Consumer<ProfilingResult> { profilingResult ->
    if (profilingResult.errorCode != ProfilingResult.ERROR_NONE) {
        // upload profile result to server for further analysis
        setupProfileUploadWorker(profilingResult.resultFilePath)
    }
    profilingManager.registerForAllProfilingResults(mainExecutor,
                                                    resultCallback)
    profilingManager.addProfilingTriggers(triggers)
}

JobDebugInfo API

Android 17 引入了新的 JobDebugInfo API，可帮助开发者调试其 JobScheduler 作业，了解作业未运行的原因、运行时长以及其他汇总信息。

扩展后的 JobDebugInfo API 的第一个方法是 getPendingJobReasonStats()，该方法会返回一个映射，其中包含作业处于待执行状态的原因及其各自的累计待执行时长。此方法将 getPendingJobReasonsHistory() 和 getPendingJobReasons() 方法联接在一起，可让您了解预定作业未按预期运行的原因，但通过在单个方法中同时提供时长和作业原因，简化了信息检索。

例如，对于指定的 jobId，该方法可能会返回 PENDING_JOB_REASON_CONSTRAINT_CHARGING 和 60000 毫秒的时长，表示作业因未满足充电约束而处于等待状态 60000 毫秒。

通过为允许空闲时运行的闹钟提供监听器支持，减少唤醒锁定

Android 17 引入了 AlarmManager.setExactAndAllowWhileIdle 的新变体，该变体接受 OnAlarmListener 而不是 PendingIntent。这种基于回调的新机制非常适合目前依赖于连续唤醒锁来执行定期任务的应用，例如维护套接字连接的消息传递应用。

隐私权

Android 17 包含以下新功能，可提升用户隐私保护。

加密客户端 Hello (ECH) 平台支持

Android 17 引入了对加密客户端 Hello (ECH) 的平台支持，这是对网络通信的一项重大隐私增强功能。ECH 是一项 TLS 1.3 扩展，可在初始 TLS 握手期间加密服务器名称指示 (SNI)。这种加密有助于保护用户隐私，因为它可以让网络中介更难识别应用连接到的特定网域。

该平台现在包含网络库实现 ECH 所需的 API。这包括 DnsResolver 中的新功能，用于查询包含 ECH 配置的 HTTPS DNS 记录；以及 Conscrypt 的 SSLEngine 和 SSLSocket 中的新方法，用于在连接到网域时传入这些配置来启用 ECH。开发者可以通过网络安全配置文件中的新 <domainEncryption> 元素来配置 ECH 偏好设置，例如机会性地启用 ECH 或强制使用 ECH，这些设置可全局应用，也可按网域应用。

预计 HttpEngine、WebView 和 OkHttp 等热门联网库将在未来的更新中集成这些平台 API，从而使应用能够更轻松地采用 ECH 并增强用户隐私保护。

如需了解详情，请参阅加密的客户端 Hello 文档。

Android 联系人选择器

Android 联系人选择工具是一个标准化的可浏览界面，供用户与您的应用分享联系人。该选择工具适用于搭载 Android 17（API 级别 37）或更高版本的设备，可提供一种可保护隐私的替代方案，以取代广泛的 READ_CONTACTS 权限。您的应用无需请求访问用户的整个地址簿，而是指定所需的数据字段（例如电话号码或电子邮件地址），然后用户选择要分享的特定联系人。这样，您的应用便只能读取所选数据，从而确保精细控制，同时提供一致的用户体验，并具有内置搜索、个人资料切换和多选功能，而无需构建或维护界面。

如需了解详情，请参阅联系人选择工具文档。

安全

Android 17 添加了以下新功能，以提升设备和应用安全性。

Android 高级保护模式 (AAPM)

Android 高级保护模式为 Android 用户提供了一套强大的新安全功能，标志着在保护用户（尤其是面临较高风险的用户）免遭复杂攻击方面迈出了重要一步。AAPM 是一项选择启用功能，只需进行一项配置设置即可激活。用户可以随时启用该功能，以应用一套主观的安全保护措施。

这些核心配置包括：禁止安装未知来源的应用（旁加载）、限制 USB 数据信号传输，以及强制执行 Google Play 保护机制扫描，从而显著减小设备的攻击面。开发者可以使用 AdvancedProtectionManager API 与此功能集成，以检测模式的状态，从而使应用能够在用户选择启用此模式时自动采用强化型安全姿态或限制高风险功能。

PQC APK 签名

Android 现在支持混合 APK 签名方案，以保护应用的签名身份免受利用量子计算的攻击的潜在威胁。此功能引入了一种新的 APK 签名方案，可让您将经典签名密钥（例如 RSA 或 EC）与新的后量子加密 (PQC) 算法 (ML-DSA) 配对。

这种混合方法可确保您的应用在未来免受量子攻击，同时与依赖于经典签名验证的旧版 Android 和设备保持完全的向后兼容性。

对开发者的影响

使用 Play 应用签名的应用：如果您使用 Play 应用签名，可以等待 Google Play 为您提供使用 Google Play 生成的 PQC 密钥升级混合签名的选项，从而确保您的应用受到保护，而无需手动管理密钥。
使用自行管理的密钥的应用：自行管理签名密钥的开发者可以利用更新后的 Android build 工具（例如 apksigner）轮换到混合身份，将 PQC 密钥与新的经典密钥相结合。（您必须创建新的经典密钥，无法重复使用旧密钥。）

连接

Android 17 添加了以下功能，以改进设备和应用连接。

受限卫星网络

实现优化，使应用能够在低带宽卫星网络上有效运行。

用户体验和系统界面

Android 17 包含以下变更，旨在提升用户体验。

专用 Google 助理音量音频流

Android 17 为 Google 助理应用引入了专用的 Google 助理音量流，以便使用 USAGE_ASSISTANT 进行播放。此项更改将 Google 助理音频与标准媒体流分离，让用户可以单独控制这两个音量。这样便可实现以下场景：将媒体播放静音，同时保持 Google 助理响应的可听性，反之亦然。

有权访问新的 MODE_ASSISTANT_CONVERSATION 音频模式的 Google 助理应用可以进一步提高音量控制的一致性。Google 助理应用可以使用此模式向系统提供有关活跃 Google 助理会话的提示，确保可以在活跃 USAGE_ASSISTANT 播放之外或使用连接的蓝牙外设控制 Google 助理流。

Handoff

切换是 Android 17 中新增的一项功能和 API，应用开发者可以将其集成到应用中，以便为用户提供跨设备连续性。它允许用户在一个 Android 设备上启动应用 activity，然后将其转移到另一个 Android 设备。Handoff 在用户设备的后台运行，并通过各种入口点（例如接收设备上的启动器和任务栏）显示用户附近其他设备上的可用活动。

应用可以指定 Handoff 来启动相同的原生 Android 应用（如果该应用已安装在接收设备上且可供使用）。在此应用到应用流程中，用户通过深层链接跳转到指定 activity。或者，应用到网站切换功能可以作为后备选项提供，也可以通过网址切换功能直接实现。

切换支持是按 activity 实现的。如需启用 Handoff，请针对 activity 调用 setHandoffEnabled() 方法。可能需要随切换传递其他数据，以便接收设备上重新创建的 activity 可以恢复适当的状态。实现 onHandoffActivityDataRequested() 回调以返回 HandoffActivityData 对象，该对象包含用于指定 Handoff 应如何处理并在接收设备上重新创建 activity 的详细信息。

实时更新 - 语义颜色 API

在 Android 17 中，实时更新启动了语义着色 API，以支持具有通用含义的颜色。

以下类支持语义着色：

填色游戏

绿色：与安全相关。此颜色应在以下情况下使用：让别人知道您处于安全状态。
橙色：用于表示警告和标记物理危险。在用户需要注意以设置更好的保护设置的情况下，应使用此颜色。
红色：通常表示危险、停止。它应在需要人们紧急关注的情况下显示。
蓝色：中性颜色，适用于信息性内容，应与其他内容区分开来。

以下示例展示了如何将语义样式应用于通知中的文本：

  val ssb = SpannableStringBuilder()
        .append("Colors: ")
        .append("NONE", Notification.createSemanticStyleAnnotation(SEMANTIC_STYLE_UNSPECIFIED), 0)
        .append(", ")
        .append("INFO", Notification.createSemanticStyleAnnotation(SEMANTIC_STYLE_INFO), 0)
        .append(", ")
        .append("SAFE", Notification.createSemanticStyleAnnotation(SEMANTIC_STYLE_SAFE), 0)
        .append(", ")
        .append("CAUTION", Notification.createSemanticStyleAnnotation(SEMANTIC_STYLE_CAUTION), 0)
        .append(", ")
        .append("DANGER", Notification.createSemanticStyleAnnotation(SEMANTIC_STYLE_DANGER), 0)

    Notification.Builder(context, channelId)
          .setSmallIcon(R.drawable.ic_icon)
          .setContentTitle("Hello World!")
          .setContentText(ssb)
          .setOngoing(true)
              .setRequestPromotedOngoing(true)

适用于 Android 17 的 UWB 下行链路 TDoA API

通过下行链路到达时间差 (DL-TDoA) 测距，设备可以通过测量信号的相对到达时间来确定其相对于多个锚点的位置。

以下代码段演示了如何初始化 [测距管理器][ranging-manager-ref]、验证设备功能并启动 DL-TDoA 会话：

Kotlin

class RangingApp {

    fun initDlTdoa(context: Context) {
        // Initialize the Ranging Manager
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Register for device capabilities
        val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback {
            override fun onRangingCapabilities(capabilities: RangingCapabilities) {
                // Make sure Dl-TDoA is supported before starting the session
                if (capabilities.uwbCapabilities != null && capabilities.uwbCapabilities!!.isDlTdoaSupported) {
                    startDlTDoASession(context)
                }
            }
        }
        rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback)
    }

    fun startDlTDoASession(context: Context) {

        // Initialize the Ranging Manager
        val rangingManager = context.getSystemService(RangingManager::class.java)

        // Create session and configure parameters
        val executor = Executors.newSingleThreadExecutor()
        val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback())
        val rangingRoundIndexes = byteArrayOf(0)
        val config: ByteArray = byteArrayOf() // OOB config data
        val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes)

        val rangingDevice = RangingDevice.Builder().build()
        val rawTagDevice = RawRangingDevice.Builder()
            .setRangingDevice(rangingDevice)
            .setDlTdoaRangingParams(params)
            .build()

        val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build()

        val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig)
            .setSessionConfig(SessionConfig.Builder().build())
            .build()

        // Start the ranging session
        rangingSession.start(preference)
    }
}

private class RangingSessionCallback : RangingSession.Callback {
    override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) {
        // Process measurement results here
    }
}

Java

public class RangingApp {

    public void initDlTdoa(Context context) {

        // Initialize the Ranging Manager
        RangingManager rangingManager = context.getSystemService(RangingManager.class);

        // Register for device capabilities
        RangingManager.CapabilitiesCallback capabilitiesCallback = new RangingManager.RangingCapabilitiesCallback() {
            @Override
            public void onRangingCapabilities(RangingCapabilities capabilities) {
                // Make sure Dl-TDoA is supported before starting the session
                if (capabilities.getUwbCapabilities() != null && capabilities.getUwbCapabilities().isDlTdoaSupported()) {
                    startDlTDoASession(context);
                }
            }
        };
        rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback);
    }

    public void startDlTDoASession(Context context) {
        RangingManager rangingManager = context.getSystemService(RangingManager.class);

        // Create session and configure parameters
        Executor executor = Executors.newSingleThreadExecutor();
        RangingSession rangingSession = rangingManager.createRangingSession(executor, new RangingSessionCallback());
        byte[] rangingRoundIndexes = new byte[] {0};
        byte[] config = new byte[0]; // OOB config data
        DlTdoaRangingParams params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes);

        RangingDevice rangingDevice = new RangingDevice.Builder().build();
        RawRangingDevice rawTagDevice = new RawRangingDevice.Builder()
                .setRangingDevice(rangingDevice)
                .setDlTdoaRangingParams(params)
                .build();

        RawDtTagRangingConfig dtTagConfig = new RawDtTagRangingConfig.Builder(rawTagDevice).build();

        RangingPreference preference = new RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig)
                .setSessionConfig(new SessionConfig.Builder().build())
                .build();

        // Start the ranging session
        rangingSession.start(preference);
    }

    private static class RangingSessionCallback implements RangingSession.Callback {

        @Override
        public void onDlTdoaResults(RangingDevice peer, DlTdoaMeasurement measurement) {
            // Process measurement results here
        }
    }
}

带外 (OOB) 配置

以下代码段提供了 Wi-Fi 和 BLE 的 DL-TDoA OOB 配置数据示例：

Java

// Wifi Configuration
byte[] wifiConfig = {
    (byte) 0xDD, (byte) 0x2D, (byte) 0x5A, (byte) 0x18, (byte) 0xFF, // Header
    (byte) 0x5F, (byte) 0x19, // FiRa Sub-Element
    (byte) 0x02, (byte) 0x00, // Profile ID
    (byte) 0x06, (byte) 0x02, (byte) 0x20, (byte) 0x08, // MAC Address
    (byte) 0x14, (byte) 0x01, (byte) 0x0C, // Preamble Index
    (byte) 0x27, (byte) 0x02, (byte) 0x08, (byte) 0x07, // Vendor ID
    (byte) 0x28, (byte) 0x06, (byte) 0xCA, (byte) 0xC8, (byte) 0xA6, (byte) 0xF7, (byte) 0x6F, (byte) 0x08, // Static STS IV
    (byte) 0x08, (byte) 0x02, (byte) 0x60, (byte) 0x09, // Slot Duration
    (byte) 0x1B, (byte) 0x01, (byte) 0x0A, // Slots per RR
    (byte) 0x09, (byte) 0x04, (byte) 0xE8, (byte) 0x03, (byte) 0x00, (byte) 0x00, // Duration
    (byte) 0x9F, (byte) 0x04, (byte) 0x67, (byte) 0x45, (byte) 0x23, (byte) 0x01  // Session ID
};

// BLE Configuration
byte[] bleConfig = {
    (byte) 0x2D, (byte) 0x16, (byte) 0xF4, (byte) 0xFF, // Header
    (byte) 0x5F, (byte) 0x19, // FiRa Sub-Element
    (byte) 0x02, (byte) 0x00, // Profile ID
    (byte) 0x06, (byte) 0x02, (byte) 0x20, (byte) 0x08, // MAC Address
    (byte) 0x14, (byte) 0x01, (byte) 0x0C, // Preamble Index
    (byte) 0x27, (byte) 0x02, (byte) 0x08, (byte) 0x07, // Vendor ID
    (byte) 0x28, (byte) 0x06, (byte) 0xCA, (byte) 0xC8, (byte) 0xA6, (byte) 0xF7, (byte) 0x6F, (byte) 0x08, // Static STS IV
    (byte) 0x08, (byte) 0x02, (byte) 0x60, (byte) 0x09, // Slot Duration
    (byte) 0x1B, (byte) 0x01, (byte) 0x0A, // Slots per RR
    (byte) 0x09, (byte) 0x04, (byte) 0xE8, (byte) 0x03, (byte) 0x00, (byte) 0x00, // Duration
    (byte) 0x9F, (byte) 0x04, (byte) 0x67, (byte) 0x45, (byte) 0x23, (byte) 0x01  // Session ID
};

如果您无法使用 OOB 配置（因为该配置缺失），或者需要更改不在 OOB 配置中的默认值，则可以使用 DlTdoaRangingParams.Builder 构建参数，如以下代码段所示。您可以使用这些参数来代替 DlTdoaRangingParams.createFromFiraConfigPacket()：

Kotlin

val dlTdoaParams = DlTdoaRangingParams.Builder(1)
    .setComplexChannel(UwbComplexChannel.Builder()
            .setChannel(9).setPreambleIndex(10).build())
    .setDeviceAddress(deviceAddress)
    .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04))
    .setRangingIntervalMillis(240)
    .setSlotDuration(UwbRangingParams.DURATION_2_MS)
    .setSlotsPerRangingRound(20)
    .setRangingRoundIndexes(byteArrayOf(0x01, 0x05))
    .build()

Java

DlTdoaRangingParams dlTdoaParams = new DlTdoaRangingParams.Builder(1)
    .setComplexChannel(new UwbComplexChannel.Builder()
            .setChannel(9).setPreambleIndex(10).build())
    .setDeviceAddress(deviceAddress)
    .setSessionKeyInfo(new byte[]{0x01, 0x02, 0x03, 0x04})
    .setRangingIntervalMillis(240)
    .setSlotDuration(UwbRangingParams.DURATION_2_MS)
    .setSlotsPerRangingRound(20)
    .setRangingRoundIndexes(new byte[]{0x01, 0x05})
    .build();

[ranging-manager-ref]：/reference/android/ranging/RangingManager

全文转载：Android 17 行为变更：以 Android 17 或更高版本为目标平台的应用

Wed, 17 Jun 2026 12:03:00 +0800

原文标题：Android 17 行为变更：以 Android 17 或更高版本为目标平台的应用

作者/来源：Android Developers / Android Developers

原文链接：https://developer.android.com/about/versions/17/behavior-changes-17?hl=zh-cn

许可证/授权：Android Developers Content License

与之前的版本一样，Android 17 包含一些可能会影响应用的行为变更。以下行为变更仅影响以 Android 17 或更高版本为目标平台的应用。如果您的应用以 Android 17 或更高版本为目标平台，则应根据情况修改应用，以支持这些行为。

无论应用的 targetSdkVersion 为何，都请务必查看对 Android 17 上运行的所有应用都有影响的行为变更列表。

核心功能

Android 17 包含以下变更，这些变更会修改或扩展 Android 系统的各种核心功能。

MessageQueue 的新无锁实现

从 Android 17 开始，以 Android 17（API 级别 37）或更高版本为目标平台的应用会收到 android.os.MessageQueue 的新无锁实现。新实现可提升性能并减少丢帧，但可能会破坏反映 MessageQueue 私有字段和方法的客户端。

如需了解详情（包括缓解措施），请参阅 MessageQueue 行为变更指南。

静态 final 字段现在不可修改

在以 Android 17（API 级别 37）或更高版本为目标平台的 Android 17 或更高版本上运行的应用无法更改 static final 字段。如果应用尝试使用反射更改 static final 字段，则会导致 IllegalAccessException。尝试通过 JNI API（例如 SetStaticLongField()）修改其中一个字段会导致应用崩溃。

无障碍

Android 17 进行了以下变更，以改进无障碍功能。

此功能引入了新的 AccessibilityEvent 和 TextAttribute API，以增强屏幕阅读器针对 CJKV 语言输入的语音反馈。CJKV IME 应用现在可以指示在文本撰写期间是否已选择文本转换候选内容。具有编辑字段的应用可以在发送文本更改无障碍事件时指定文本更改类型。例如，应用可以指定在文本撰写期间发生了文本更改，或者文本更改是由提交导致的。这样做可让屏幕阅读器等无障碍服务根据文本修改的性质提供更精确的反馈。

应用采用量

IME 应用：在编辑字段中设置正在撰写的文本时，IME 可以使用 TextAttribute.Builder.setTextSuggestionSelected() 来指明是否选择了特定的转换候选对象。
具有“编辑字段”权限的应用：维护自定义 InputConnection 的应用可以通过调用 TextAttribute.isTextSuggestionSelected() 来检索候选选择数据。然后，这些应用在调度 TYPE_VIEW_TEXT_CHANGED 事件时应调用 AccessibilityEvent.setTextChangeTypes()。如果应用以 Android 17（API 级别 37）为目标平台，并使用标准 TextView，则默认启用此功能。（也就是说，TextView 将负责从 IME 检索数据，并在向无障碍服务发送事件时设置文本更改类型）。
无障碍服务：处理 TYPE_VIEW_TEXT_CHANGED 事件的无障碍服务可以调用 AccessibilityEvent.getTextChangeTypes() 来识别修改的性质，并相应地调整其反馈策略。

隐私权

Android 17 包含以下变更，旨在提升用户隐私保护。

已启用 ECH（加密客户端 Hello）

Android 17 引入了对加密客户端问候 (ECH) 的平台支持。ECH 是一种 TLS 扩展，可通过加密 TLS 握手中的服务器名称指示 (SNI) 来增强用户隐私保护。这种加密有助于防止网络观察者轻松识别您的应用所连接的特定网域。

对于以 Android 17（API 级别 37）或更高版本为目标平台的应用，ECH 用于 TLS 连接。只有当应用使用的网络库（例如 HttpEngine、WebView 或 OkHttp）已集成 ECH 支持，并且远程服务器也支持 ECH 协议时，ECH 才会处于活跃状态。如果无法协商 ECH，客户端会发送一个包含随机内容的 ECH 扩展（一种称为 ECH GREASE 的机制）。如需详细了解 ECH GREASE 的工作原理，请参阅 RFC 9849。

为了让应用能够自定义此行为，Android 17 向网络安全配置文件添加了一个新的 <domainEncryption> 元素。开发者可以在 <base-config> 或 <domain-config> 标记中使用 <domainEncryption>，以全局或按网域的方式选择 ECH 模式（例如 "enabled" 或 "disabled"）。

如需了解详情，请参阅加密客户端问候文档。

以 Android 17 为目标平台的应用需要本地网络权限

Android 17 引入了 ACCESS_LOCAL_NETWORK 运行时权限，以保护用户免遭未经授权的本地网络访问。由于此权限属于现有的 NEARBY_DEVICES 权限组，因此系统不会再次提示已授予其他 NEARBY_DEVICES 权限的用户。这项新要求可防止恶意应用利用不受限制的本地网络访问权限进行隐秘的用户跟踪和指纹识别。通过声明和请求此权限，您的应用可以发现并连接到局域网 (LAN) 中的设备，例如智能家居设备或投屏接收器。

以 Android 17（API 级别 37）或更高版本为目标平台的应用现在可以通过两种方式与 LAN 设备保持通信：采用系统介导的、可保护隐私的设备选择器来跳过权限提示，或者在运行时明确请求此新权限以保持本地网络通信。

如需了解详情，请参阅本地网络权限文档。

在实体设备上隐藏密码

如果应用以 Android 17（API 级别 37）或更高版本为目标平台，并且用户使用的是实体输入设备（例如外接键盘），Android 操作系统会对密码字段中的所有字符应用新的 show_passwords_physical 设置。默认情况下，该设置会隐藏所有密码字符。

Android 系统会显示用户最后输入的密码字符，以帮助用户查看是否输错了密码。不过，对于较大的外接键盘，此功能就没那么必要了。此外，配备外接键盘的设备通常具有较大的显示屏，这会增加他人看到输入密码的风险。

如果用户使用的是设备触摸屏，系统会应用新的 show_passwords_touch 设置。

针对标准短信的 OTP 保护

从 Android 17 开始，Android 将扩展其短信验证码保护功能，以适用于标准短信（包含验证码但不使用 WebOTP 或 SMS Retriever 格式的短信）。对于以 Android 17（API 级别 37）或更高版本为目标平台的应用，这些短信在收到后三小时内不会提供。此延迟旨在帮助防止动态密码劫持。在这三小时的延迟期间，系统会保留 SMS_RECEIVED_ACTION广播，并过滤短信提供商数据库查询。延迟结束后，这些应用即可使用短信。

某些应用（例如默认短信助理应用、已连接的设备配套应用等）不受此延迟限制。所有依赖于读取短信来提取动态密码的应用都应改用 SMS Retriever 或 SMS User Consent API，以确保功能持续可用。

安全

Android 17 对设备和应用安全性进行了以下改进。

活动安全性

在 Android 17 中，平台继续向“默认安全”架构转变，引入了一系列旨在缓解网络钓鱼、互动劫持和混淆代理攻击等高严重性漏洞的增强功能。此更新要求开发者明确选择启用新的安全标准，以保持应用兼容性和用户保护。

对开发者的主要影响包括：

BAL 安全加固和改进的选择启用：我们正在优化后台活动启动 (BAL) 限制，方法是将保护范围扩展到 IntentSender。开发者必须从旧版 MODE_BACKGROUND_ACTIVITY_START_ALLOWED 常量迁移。相反，您应采用精细控制，例如 MODE_BACKGROUND_ACTIVITY_START_ALLOW_IF_VISIBLE，它将活动启动限制为调用应用可见的场景，从而显著缩小攻击面。
采用工具：开发者应利用严格模式和更新后的 lint 检查来识别旧版模式，并确保为未来的目标 SDK 要求做好准备。

默认启用 CT

如果应用以 Android 17（API 级别 37）或更高版本为目标平台，则默认启用证书透明度 (CT)。（在 Android 16 上，CT 可用，但应用必须选择启用。）

更安全的原生 DCL - C

如果您的应用以 Android 17（API 级别 37）或更高版本为目标平台，则 Android 14 中针对 DEX 和 JAR 文件引入的更安全的动态代码加载 (DCL) 保护功能现在也适用于原生库。

使用 System.load() 加载的所有原生文件都必须标记为只读。否则，系统会抛出 UnsatisfiedLinkError。

我们建议应用尽可能避免动态加载代码，因为这样做会大大增加应用因代码注入或代码篡改而遭到入侵的风险。

限制 CP2 数据视图中的 PII 字段

对于以 Android 17（API 级别 Android 17（API 级别 37））及更高版本为目标平台的应用，联系人提供程序 2 (CP2) 会限制数据视图中包含某些个人身份信息 (PII) 的列。启用此变更后，这些列将从数据视图中移除，以增强用户隐私保护。受限列包括：

如果应用正在使用 ContactsContract.Data 中的这些列，则可以通过与 RAW_CONTACT_ID 联接，改为从 ContactsContract.RawContacts 中提取这些列。

在 CP2 中强制执行严格的 SQL 检查

For apps targeting Android 17 (API level Android 17 (API level 37)) and higher, Contacts Provider 2 (CP2) enforces strict SQL query validation when the ContactsContract.Data table is accessed without READ_CONTACTS permission.

With this change, if an app doesn't have READ_CONTACTS permission, StrictColumns and StrictGrammar options are set when querying the ContactsContract.Data table. If a query uses a pattern that isn't compatible with these, it will be rejected and cause an exception to be thrown.

媒体

Android 17 针对媒体行为做了以下更改。

后台音频安全加固

从 Android 17 开始，音频框架对后台音频互动（包括音频播放、音频焦点请求和音量更改 API）强制执行限制，以确保这些更改是由用户有意启动的。

部分音频限制适用于所有应用。不过，如果应用以 Android 17（API 级别 37）为目标平台，则限制会更加严格。如果这些应用在后台运行时与音频互动，则必须有前台服务正在运行。此外，应用还必须满足以下一项或两项要求：

前台服务必须具有仅在使用时授予的权限 (WIU)。
应用必须具有精确闹钟权限，并且正在与 USAGE_ALARM 音频流互动。

如需了解详情（包括缓解措施），请参阅后台音频安全加固。

设备规格

Android 17 包含以下变更，可改善各种尺寸和外形规格的设备上的用户体验。

平台 API 变更，用于忽略大屏设备 (sw>=600dp) 上的屏幕方向、尺寸调整能力和宽高比限制

We introduced Platform API changes in Android 16 to ignore orientation, aspect ratio, and resizability restrictions on large screens (sw >= 600dp) for apps targeting API level 36 or higher. Developers have the option to opt out of these changes with SDK 36, but this opt-out will no longer be available for apps that target Android 17 (API level 37) or higher.

For more information, see Restrictions on orientation and resizability are ignored.

连接

Android 17 引入了以下变更，以提高一致性并与蓝牙 RFCOMM 套接字的标准 Java InputStream 行为保持一致。

针对 RFCOMM 的一致 BluetoothSocket read() 行为

对于以 Android 17（API 级别 37）为目标平台的应用， read() 方法从InputStream 获取的基于 RFCOMM 的 BluetoothSocket 现在会在套接字关闭或连接断开时返回 -1。

此更改使 RFCOMM 套接字行为与 LE CoC 套接字保持一致，并与标准 InputStream.read() 文档保持一致，该文档指出，当到达流的末尾时，系统会返回 -1。

仅依赖于捕获 IOException 以跳出读取循环的应用可能会受到此更改的影响，并且应更新 BluetoothSocket 读取循环以明确检查返回值 -1。这可确保在远程设备断开连接或套接字关闭时，循环正确终止。如需查看推荐的实现示例，请参阅传输蓝牙数据指南中的代码段。

全文转载：Android 17 行为变更：所有应用

Wed, 17 Jun 2026 12:00:00 +0800

原文标题：Android 17 行为变更：所有应用

作者/来源：Android Developers / Android Developers

原文链接：https://developer.android.com/about/versions/17/behavior-changes-all?hl=zh-cn

许可证/授权：Android Developers Content License

Android 17 平台包含一些可能会影响您的应用的行为变更。以下行为变更将影响在 Android 17 上运行的所有应用，无论采用哪种 targetSdkVersion 都不例外。您应该测试您的应用，然后根据需要酌情修改，以便支持这些变更。

此外，请务必查看仅影响以 Android 17 为目标平台的应用的行为变更列表。

核心功能

Android 17（API 级别 37）包含以下变更，这些变更会修改或扩展 Android 系统的各种核心功能。

应用内存限制

Android 17 引入了基于设备总 RAM 的应用内存限制，以便为您的应用和 Android 用户打造更稳定、更确定的环境。在 Android 17 中，系统会保守地设置限制，以建立系统基准，在极端内存泄漏和其他异常情况导致系统范围内的不稳定（导致界面卡顿、耗电过快和应用被终止）之前，针对这些情况采取措施。虽然我们预计此变化对绝大多数应用会话的影响微乎其微，但我们建议您遵循以下内存最佳实践，包括建立内存基准。

您可以通过在 ApplicationExitInfo 中调用 getDescription 来确定应用会话是否受到影响；如果应用受到影响，退出原因将为 REASON_OTHER，说明将包含字符串 "MemoryLimiter:AnonSwap" 以及其他信息。您还可以将 TRIGGER_TYPE_ANOMALY 与基于触发器的分析搭配使用，以获取在达到内存限制时收集的堆转储。

管理应用的内存文档提供的信息可帮助您诊断应用的内存问题并优化其资源消耗。

在内存受限的情况下测试应用的运行情况

您可以使用 Android 调试桥 (adb) 调整或停用任何施加内存限制的设备上的内存限制。shell 命令 am 提供了三个用于调整内存限制的子命令。（这些命令对未施加内存限制的设备没有影响。）

am memory-limiter ignore <uid>|none|all
am memory-limiter manual <pid> <limit>|max|none
am memory-limiter status

ignore: 指示内存限制器忽略部分或全部进程。传递 UID（Android 用户 ID）会指示内存限制器忽略对与该 UID 相关联的所有进程的强制执行。您还可以传递 all（忽略所有应用）或 none（不忽略任何应用）。传递 none 会替换之前对 am memory-limiter ignore 的任何调用。; 如果您指示内存限制器忽略某个 UID，您仍然可以通过调用 am memory-limiter manual 为应用内的进程应用手动内存限制。
manual: 指示系统对具有指定 PID（进程 ID）的进程施加内存限制。内存限制以整数形式的 MB 数指定；例如，传递 30 指定进程的内存限制为 30 MB。传递 max 会移除相应进程的所有内存限制。传递 none 会移除对进程设置的所有手动限制，从而恢复系统的默认限制（如果有）。
status: 报告内存限制器的当前状态。该状态包括对可见进程和非可见进程施加的内存限制。

隐私权

Android 17 包含以下变更，旨在提升用户隐私保护。

动态短信密码保护

从 Android 17 开始，Android 将扩大对包含一次性密码 (OTP) 的短信的保护范围。

在之前的 Android 版本中，此保护主要侧重于 SMS Retriever 格式。对于大多数应用，包含 SMS Retriever 哈希的消息的递送延迟了 3 小时。不过，某些应用（例如默认短信处理程序）不受此延迟的影响，拥有哈希的应用也不受此延迟的影响。

从 Android 17 开始，此保护也适用于 WebOTP 格式的消息。如果应用有权读取短信，但不是 WebOTP 消息的预期接收者（由网域验证确定），则该应用在收到消息后 3 小时内无法访问该消息。此变更旨在提高用户安全性，确保只有与消息中提及的网域关联的应用才能以编程方式读取验证码。

在这 3 小时的延迟期间，系统会保留 SMS_RECEIVED_ACTION 广播，并过滤短信提供商数据库查询。延迟结束后，这些应用即可使用短信。此变更适用于 所有应用，无论其目标 API 级别如何。

某些应用（例如默认短信助理应用、关联设备配套应用等）不受此延迟的影响。所有依赖于读取短信来提取 OTP 的应用都应过渡到使用 SMS Retriever 或 SMS User Consent API，以确保功能持续可用。

安全

Android 17 包含以下设备和应用安全方面的改进。

usesClearTraffic 弃用计划

In a future release, we plan to deprecate the usesCleartextTraffic element. Apps that need to make unencrypted (HTTP) connections should migrate to using a network security configuration file, which lets you specify which domains your app needs to make cleartext connections to.

Be aware that network security configuration files are only supported on API levels 24 and higher. If your app has a minimum API level lower than 24, you should do both of the following:

Set the usesCleartextTraffic attribute to true
Use a network configuration file

If your app's minimum API level is 24 or higher, you can use a network configuration file and you don't need to set usesCleartextTraffic.

限制隐式 URI 授权

目前，如果应用启动的 intent 具有 URI，且该 URI 具有操作 ACTION_SEND、ACTION_SEND_MULTIPLE或 ACTION_IMAGE_CAPTURE，则系统会自动向目标应用授予读取和写入 URI 权限。从 Android 18 开始，系统将不再自动授予这些权限。因此，我们建议应用明确授予相关 URI 权限，而不是依赖系统授予这些权限。

如需检测应用中这些 intent 的使用情况，请将 StrictMode 与 detectImplicitUriPermissionGrant() 结合使用，以触发违规行为：

Kotlin

val policy = StrictMode.VmPolicy.Builder()
    .detectImplicitUriPermissionGrant()
    .penaltyLog()
    .build()
StrictMode.setVmPolicy(policy)

Java

StrictMode.VmPolicy policy = new StrictMode.VmPolicy.Builder()
    .detectImplicitUriPermissionGrant()
    .penaltyLog()
    .build();
StrictMode.setVmPolicy(policy);

或者，您也可以监控包含消息 Please set the grant explicitly in the app 的已记录异常，该消息会在系统隐式设置授予时显示。您可以使用以下 adb 命令监控这些日志：

adb logcat | grep "Please set the grant explicitly in the app"

如需明确授予必要的权限，请将 FLAG_GRANT_READ_URI_PERMISSION标志添加到ACTION_SEND和 ACTION_SEND_MULTIPLEintent：

Kotlin

intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)

Java

intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);

对于 ACTION_IMAGE_CAPTURE intent，请同时添加FLAG_GRANT_READ_URI_PERMISSION 和 FLAG_GRANT_WRITE_URI_PERMISSION 标志：

Kotlin

intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_GRANT_WRITE_URI_PERMISSION)

Java

intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);

每个应用的密钥库限制

应用应避免在 Android 密钥库中创建过多的密钥，因为它是设备上所有应用的共享资源。从 Android 17 开始，系统会强制限制应用可拥有的密钥数量。对于以 Android 17（API 级别 37）或更高版本为目标平台的非系统应用，密钥数量上限为 50,000 个；对于所有其他应用，密钥数量上限为 200,000 个。无论系统应用以哪个 API 级别为目标，其密钥数量上限均为 20 万。

如果应用尝试创建超出限制的密钥，则创建会失败并显示 KeyStoreException。异常的消息字符串包含有关密钥限制的信息。如果应用针对异常调用 getNumericErrorCode()，则返回值取决于应用的目标 API 级别：

如果应用以 Android 17（API 级别 37）或更高版本为目标平台，getNumericErrorCode() 会返回新的 ERROR_TOO_MANY_KEYS 值。
所有其他应用：getNumericErrorCode() 返回 ERROR_INCORRECT_USAGE。

阻止跨资料环回流量

从 Android 17 开始，默认情况下不再允许跨个人资料环回流量。同一个人资料内的环回流量不受影响。此项变更适用于在 Android 17 或更高版本上运行的所有应用，无论应用以哪个 API 级别为目标平台。

用户体验和系统界面

Android 17 包含以下变更，旨在打造更一致、更直观的用户体验。

在旋转后恢复默认 IME 可见性

从 Android 17 开始，当设备的配置发生变化（例如，通过旋转）且应用本身未处理此变化时，系统不会恢复之前的 IME 可见性。

如果应用经历了它无法处理的配置更改，并且应用需要在更改后显示键盘，您必须明确请求此行为。您可以通过以下方式之一提出此要求：

将 android:windowSoftInputMode 属性设置为 stateAlwaysVisible。
在 activity 的 onCreate() 方法中以编程方式请求显示软键盘，或添加 onConfigurationChanged() 方法。

人工输入

Android 17 包含以下变更，这些变更会影响应用与键盘和触控板等人工输入设备的互动方式。

在指针捕获期间，触控板默认传递相对事件

从 Android 17 开始，如果应用使用 View.requestPointerCapture() 请求捕获指针，并且用户使用触控板，系统会识别用户触摸操作产生的指针移动和滚动手势，并以与捕获的鼠标产生的指针和滚轮移动相同的方式将这些信息报告给应用。在大多数情况下，这使得支持捕获鼠标的应用无需为触控板添加特殊的处理逻辑。如需了解详情，请参阅 View.POINTER_CAPTURE_MODE_RELATIVE 的文档。

之前，系统不会尝试识别触控板的手势，而是以类似于触摸屏触摸的格式将原始的绝对手指位置传递给应用。如果应用仍需要此绝对数据，则应改为使用 View.POINTER_CAPTURE_MODE_ABSOLUTE 调用新的 View.requestPointerCapture(int) 方法。

媒体

Android 17 针对媒体行为做了以下更改。

后台音频安全加固

从 Android 17 开始，音频框架会对后台音频互动（包括音频播放、音频焦点请求和音量更改 API）强制执行限制，以确保这些更改是由用户有意发起的。

如果应用尝试在应用未处于有效生命周期时调用音频 API，则音频播放和音量更改 API 会以静默方式失败，而不会抛出异常或提供失败消息。音频焦点 API 会失败，并返回结果代码 AUDIOFOCUS_REQUEST_FAILED。

如需了解详情（包括缓解措施），请参阅后台音频安全加固。

连接

Android 17 包含以下变更，以增强设备连接性。

针对蓝牙绑定丢失的自主重新配对

Android 17 引入了自主重新配对功能，这是一项系统级增强功能，旨在自动解决蓝牙配对信息丢失问题。

以前，如果配对信息丢失，用户必须手动前往“设置”取消配对，然后重新配对外围设备。此功能以 Android 16 的安全改进为基础，允许系统在后台重新建立配对信息，而无需用户手动前往“设置”取消配对并重新配对外围设备。

虽然大多数应用不需要更改代码，但开发者应注意蓝牙堆栈中的以下行为变更：

新的配对上下文： ACTION_PAIRING_REQUEST 现在包含 EXTRA_PAIRING_CONTEXT extra，允许应用区分标准配对请求和自主系统发起的重新配对尝试。
有条件的密钥更新：只有在重新配对成功且新连接达到或超过之前配对信息的安全级别时，才会替换现有安全密钥。
修改后的 intent 时间：现在，只有在自主重新配对尝试失败时，才会广播 ACTION_KEY_MISSING intent。如果系统在后台成功恢复配对信息，则可以减少应用中不必要的错误处理。
用户通知：系统通过新的界面通知和对话框管理重新配对。系统会提示用户确认重新配对尝试，以确保用户了解重新连接。

外围设备制造商和配套应用开发者应验证硬件和应用是否能妥善处理配对信息转换。如需测试此行为，请使用以下任一方法模拟远程配对信息丢失：

从外围设备中手动移除配对信息
在“设置”>“已连接的设备”中手动取消配对设备