ChatGoogleGenerativeAI 集成 - 以编程方式使用文档

通过以下方式访问 Google 的生成式 AI 模型，包括 Gemini 系列： **Gemini 开发者 API** or **Vertex AI**。Gemini 开发者 API 提供快速设置和 API 密钥，非常适合个人开发者。Vertex AI 提供企业级功能并与 Google Cloud Platform 集成。

有关最新模型、模型 ID、功能、上下文窗口等信息，请访问 Google AI 文档.

概述

集成详情

类	包	可序列化	JS 支持	下载	版本
`ChatGoogleGenerativeAI`	`langchain-google-genai`	beta	✅	!PyPI - 下载	!PyPI - 版本

模型特性

工具调用	结构化输出	图像输入	音频输入	视频输入	Token 级流式处理	原生异步	Token 使用量	对数概率
✅	✅	✅	✅	✅	✅	✅	✅	⚠️

设置

要访问 Google AI 模型，您需要创建一个 Google 账户，获取 Google AI API 密钥，并安装 langchain-google-genai 集成包。

安装

pip install -U langchain-google-genai

凭证

此集成支持两个后端： **Gemini 开发者 API** 和 **Vertex AI**。后端会根据您的配置自动选择。

后端选择

后端按如下方式确定：

If GOOGLE_GENAI_USE_VERTEXAI 设置了环境变量，则使用该值
If credentials 参数提供，则使用 Vertex AI
If project 参数提供，则使用 Vertex AI
否则，使用 Gemini 开发者 API

您也可以显式设置 vertexai=True or vertexai=False 来覆盖自动检测。

Gemini Developer API

使用 API 密钥快速设置

Recommended for individual developers / new users.

前往 Google AI Studio 生成 API 密钥：

        if "GOOGLE_API_KEY" not in os.environ:
            os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter your Google AI API key: ")

集成首先检查 GOOGLE_API_KEY ，然后 GEMINI_API_KEY 作为备用。

Vertex AI with API key

使用 API 密钥身份验证的 Vertex AI

您可以使用 API 密钥身份验证来更简单地设置 Vertex AI：

或以编程方式：

        from langchain_google_genai import ChatGoogleGenerativeAI

        llm = ChatGoogleGenerativeAI(
            model="gemini-2.5-flash",
            api_key="your-api-key", # [!code highlight]
            project="your-project-id", # [!code highlight]
            vertexai=True, # [!code highlight]
        )

Vertex AI with credentials

使用服务账号或 ADC 的 Vertex AI

设置应用默认凭据 (ADC):

        gcloud auth application-default login

设置您的 Google Cloud 项目：

        # Optional: set region (defaults to us-central1)

或使用服务账号凭据：

        from google.oauth2 import service_account
        from langchain_google_genai import ChatGoogleGenerativeAI

        credentials = service_account.Credentials.from_service_account_file(
            "path/to/service-account.json",
            scopes=["https://www.googleapis.com/auth/cloud-platform"],
        )

        llm = ChatGoogleGenerativeAI(
            model="gemini-2.5-flash",
            credentials=credentials, # [!code highlight]
            project="your-project-id", # [!code highlight]
        )

环境变量

变量	用途	后端
`GOOGLE_API_KEY`	API 密钥（主要）	两者皆可（参见 `GOOGLE_GENAI_USE_VERTEXAI`)
`GEMINI_API_KEY`	API 密钥（备用）	两者皆可（参见 `GOOGLE_GENAI_USE_VERTEXAI`)
`GOOGLE_GENAI_USE_VERTEXAI`	强制使用 Vertex AI 后端（`true`/`false`）	Vertex AI
`GOOGLE_CLOUD_PROJECT`	GCP 项目 ID	Vertex AI
`GOOGLE_CLOUD_LOCATION`	GCP 区域（默认： `us-central1`）	Vertex AI

要启用模型调用的自动追踪，请设置您的 LangSmith API 密钥：

os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

实例化

现在我们可以实例化模型对象并生成响应：

Gemini Developer API

        from langchain_google_genai import ChatGoogleGenerativeAI

        model = ChatGoogleGenerativeAI(
            model="gemini-3.5-flash",
            temperature=1.0,  # Gemini 3.0+ defaults to 1.0
            max_tokens=None,
            timeout=None,
            max_retries=2,
            # other params...
        )

Vertex AI

        from langchain_google_genai import ChatGoogleGenerativeAI

        model = ChatGoogleGenerativeAI(
            model="gemini-3.5-flash",
            project="your-project-id", # [!code highlight]
            location="us-central1",  # Optional, defaults to us-central1 [!code highlight]
            temperature=1.0,  # Gemini 3.0+ defaults to 1.0
            max_tokens=None,
            timeout=None,
            max_retries=2,
            # other params...
        )

提供 project 会自动选择 Vertex AI 后端，除非您明确设置 vertexai=False.

请参阅 ChatGoogleGenerativeAI API 参考以获取完整的可用模型参数列表。

代理配置

如需使用代理，请在初始化前设置这些环境变量：

对于 SOCKS5 代理或高级代理配置，请使用 client_args parameter:

model = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    client_args={"proxy": "socks5://user:pass@host:port"},
)

自定义端点和请求头

使用 base_url 和 additional_headers 设置模型级 HTTP 选项，例如通过内部网关路由请求：

model = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    base_url="https://your-gemini-gateway.example.com",
    additional_headers={"X-Custom-Header": "value"},
)

要为单个请求传递请求头或其他 HTTP 选项，请在调用模型时提供 http_options ：

token = "..."
messages = [("human", "Hello!")]

response = model.invoke(
    messages,
    http_options={
        "headers": {
            "Authorization": f"Bearer {token}",
        }
    },
)

相同的调用时选项也适用于异步调用：

response = await model.ainvoke(
    messages,
    http_options={"headers": {"Authorization": f"Bearer {token}"}},
)

每个请求的 http_options 可以是字典或 google.genai.types.HttpOptions 对象。请求头字典会与模型级的 additional_headers合并，且每个请求的请求头值优先。模型级的 timeout 和 max_retries 设置会被保留，除非您明确覆盖 timeout or retry_options in http_options.

from google.genai.types import HttpOptions

response = model.invoke(
    messages,
    http_options=HttpOptions(
        headers={"Authorization": f"Bearer {token}"},
    ),
)

调用

messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = model.invoke(messages)
ai_msg

    AIMessage(content=[{'type': 'text', 'text': "J'adore la programmation.", 'extras': {'signature': 'EpoWCpc...'}}], additional_kwargs={}, response_metadata={'prompt_feedback': {'block_reason': 0, 'safety_ratings': []}, 'finish_reason': 'STOP', 'model_name': 'gemini-3.5-flash', 'safety_ratings': [], 'model_provider': 'google_genai'}, id='lc_run--fb732b64-1ab4-4a28-b93b-dcfb2a164a3d-0', usage_metadata={'input_tokens': 21, 'output_tokens': 779, 'total_tokens': 800, 'input_token_details': {'cache_read': 0}, 'output_token_details': {'reasoning': 772}})

    AIMessage(content="J'adore la programmation.", additional_kwargs={}, response_metadata={'prompt_feedback': {'block_reason': 0, 'safety_ratings': []}, 'finish_reason': 'STOP', 'model_name': 'gemini-2.5-flash', 'safety_ratings': []}, id='run-3b28d4b8-8a62-4e6c-ad4e-b53e6e825749-0', usage_metadata={'input_tokens': 20, 'output_tokens': 7, 'total_tokens': 27, 'input_token_details': {'cache_read': 0}})

提示

消息内容结构

Gemini 3 系列模型返回一个内容块列表来捕获思考签名。使用 .text 获取字符串内容：

    response.content  # -> [{"type": "text", "text": "Hello!", "extras": {"signature": "EpQFCp..."}}]
    response.text     # -> "Hello!"

Gemini 2.5 及更早版本为 .content.

多模态用法

Gemini 模型接受多模态输入（文本、图像、音频、视频、PDF），部分模型可以生成多模态输出。

支持的输入方法

方法	图像	视频	音频	PDF
文件上传（Files API）	✅	✅	✅	✅
Base64 内联数据	✅	✅	✅	✅
HTTP/HTTPS URLs*	✅	✅	✅	✅
GCS URI（`gs://...`)	✅	✅	✅	✅

*预览版支持 YouTube 视频输入 URL。

文件上传

您可以将文件上传到 Google 服务器并通过 URI 引用它们。这适用于 PDF、图像、视频和音频文件。

from google import genai
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI

client = genai.Client()
model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

# Upload file to Google's servers
myfile = client.files.upload(file="/path/to/your/file.pdf")
while myfile.state.name == "PROCESSING":
    time.sleep(2)
    myfile = client.files.get(name=myfile.name)

# Reference by file_id in FileContentBlock
message = HumanMessage(
    content=[
        {"type": "text", "text": "What is in the document?"},
        {
            "type": "file",
            "file_id": myfile.uri,  # or myfile.name
            "mime_type": "application/pdf",
        },
    ]
)
response = model.invoke([message])

上传后，您可以使用 file_id pattern.

图像输入

使用 HumanMessage 配合列表内容格式提供图像输入和文本。

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the image at the URL."},
            {
                "type": "image",
                "url": "https://picsum.photos/seed/picsum/200/300",
            },
        ]
    )
    response = model.invoke([message])

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the image at the URL."},
            {"type": "image_url", "image_url": "https://picsum.photos/seed/picsum/200/300"},
        ]
    )
    response = model.invoke([message])

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    image_bytes = open("path/to/your/image.jpg", "rb").read()
    image_base64 = base64.b64encode(image_bytes).decode("utf-8")
    mime_type = "image/jpeg"

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the local image."},
            {
                "type": "image",
                "base64": image_base64,
                "mime_type": mime_type,
            },
        ]
    )
    response = model.invoke([message])

    from google import genai
    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    client = genai.Client()
    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    # Upload and wait for processing
    myfile = client.files.upload(file="/path/to/image.jpg")
    while myfile.state.name == "PROCESSING":
        time.sleep(2)
        myfile = client.files.get(name=myfile.name)

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe this image."},
            {
                "type": "file",
                "file_id": myfile.uri,
                "mime_type": "image/jpeg",
            },
        ]
    )
    response = model.invoke([message])

其他支持的图像格式：

- Google Cloud Storage URI（gs://...）。确保服务账号有访问权限。

PDF 输入

提供 PDF 文件输入和文本。

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the document in a sentence."},
            {
                "type": "image_url",  # (PDFs are treated as images)
                "image_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
            },
        ]
    )
    response = model.invoke([message])

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    pdf_bytes = open("path/to/your/document.pdf", "rb").read()
    pdf_base64 = base64.b64encode(pdf_bytes).decode("utf-8")
    mime_type = "application/pdf"

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the document in a sentence."},
            {
                "type": "file",
                "base64": pdf_base64,
                "mime_type": mime_type,
            },
        ]
    )
    response = model.invoke([message])

    from google import genai
    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    client = genai.Client()
    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    # Upload and wait for processing
    myfile = client.files.upload(file="/path/to/document.pdf")
    while myfile.state.name == "PROCESSING":
        time.sleep(2)
        myfile = client.files.get(name=myfile.name)

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe the document in a sentence."},
            {
                "type": "file",
                "file_id": myfile.uri,
                "mime_type": "application/pdf",
            },
        ]
    )
    response = model.invoke([message])

音频输入

提供音频文件输入和文本。

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Summarize this audio in a sentence."},
            {
                "type": "image_url",
                "image_url": "https://example.com/audio.mp3",
            },
        ]
    )
    response = model.invoke([message])

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    audio_bytes = open("path/to/your/audio.mp3", "rb").read()
    audio_base64 = base64.b64encode(audio_bytes).decode("utf-8")
    mime_type = "audio/mpeg"

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Summarize this audio in a sentence."},
            {
                "type": "audio",
                "base64": audio_base64,
                "mime_type": mime_type,
            },
        ]
    )
    response = model.invoke([message])

    from google import genai
    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    client = genai.Client()
    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    # Upload and wait for processing
    myfile = client.files.upload(file="/path/to/audio.mp3")
    while myfile.state.name == "PROCESSING":
        time.sleep(2)
        myfile = client.files.get(name=myfile.name)

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Summarize this audio in a sentence."},
            {
                "type": "file",
                "file_id": myfile.uri,
                "mime_type": "audio/mpeg",
            },
        ]
    )
    response = model.invoke([message])

视频输入

提供视频文件输入和文本。

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    video_bytes = open("path/to/your/video.mp4", "rb").read()
    video_base64 = base64.b64encode(video_bytes).decode("utf-8")
    mime_type = "video/mp4"

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Describe what's in this video in a sentence."},
            {
                "type": "video",
                "base64": video_base64,
                "mime_type": mime_type,
            },
        ]
    )
    response = model.invoke([message])

    from google import genai
    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    client = genai.Client()
    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    # Upload and wait for processing
    myfile = client.files.upload(file="/path/to/video.mp4")
    while myfile.state.name == "PROCESSING":
        time.sleep(2)
        myfile = client.files.get(name=myfile.name)

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Summarize the video in 3 sentences."},
            {
                "type": "file",
                "file_id": myfile.uri,
                "mime_type": "video/mp4",
            },
        ]
    )
    response = model.invoke([message])

    from langchain.messages import HumanMessage
    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    message = HumanMessage(
        content=[
            {"type": "text", "text": "Summarize the video in 3 sentences."},
            {
                "type": "video",
                "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "mime_type": "video/mp4",
            },
        ]
    )
    response = model.invoke([message])

图像生成

部分模型可以生成文本和图像。详见 Gemini API 文档。

from IPython.display import Image, display
from langchain.messages import AIMessage
from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-image") # [!code highlight]

response = model.invoke("Generate a photorealistic image of a cuddly cat wearing a hat.")

def _get_image_base64(response: AIMessage) -> None:
    image_block = next(
        block
        for block in response.content
        if isinstance(block, dict) and block.get("image_url")
    )
    return image_block["image_url"].get("url").split(",")[-1]

image_base64 = _get_image_base64(response)
display(Image(data=base64.b64decode(image_base64), width=300))

使用 image_config 控制图像尺寸和质量（参见 genai.types.ImageConfig）。可在实例化时设置（适用于所有调用）或在调用时设置（每次调用覆盖）：

from langchain_google_genai import ChatGoogleGenerativeAI

# Set at instantiation (applies to all calls)
model = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash-image",
    image_config={"aspect_ratio": "16:9"}, # [!code highlight]
)

# Or override per call
response = model.invoke(
    "Generate a photorealistic image of a cuddly cat wearing a hat.",
    image_config={"aspect_ratio": "1:1"}, # [!code highlight]
)

默认情况下，图像生成模型可能同时返回文本和图像（例如。 *"好的！这是一张...的图像"*).

您可以通过设置 response_modalities parameter:

    from langchain_google_genai import ChatGoogleGenerativeAI, Modality

    model = ChatGoogleGenerativeAI(
        model="gemini-2.5-flash-image",
        response_modalities=[Modality.IMAGE],  # [!code highlight]
    )

    # All invocations will return only images
    response = model.invoke("Generate a photorealistic image of a cuddly cat wearing a hat.")

    from langchain_google_genai import ChatGoogleGenerativeAI, Modality

    model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-image")

    # Only this invocation will return images; others may return text+images
    response = model.invoke(
        "Generate a photorealistic image of a cuddly cat wearing a hat.",
        response_modalities=[Modality.IMAGE], # [!code highlight]
    )

音频生成

部分模型可以生成音频文件。详见 Gemini API 文档详情。

from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-2.5-flash-preview-tts") # [!code highlight]

response = model.invoke("Please say The quick brown fox jumps over the lazy dog")

# Base64 encoded binary data of the audio
wav_data = response.additional_kwargs.get("audio")
with open("output.wav", "wb") as f:
    f.write(wav_data)

工具调用

您可以为模型配备工具来调用。

from langchain.tools import tool
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI


# Define the tool
@tool(description="Get the current weather in a given location")
def get_weather(location: str) -> str:
    return "It's sunny."


# Initialize and bind (potentially multiple) tools to the model
model_with_tools = ChatGoogleGenerativeAI(model="gemini-3.5-flash").bind_tools([get_weather])

# Step 1: Model generates tool calls
messages = [HumanMessage("What's the weather in Boston?")]
ai_msg = model_with_tools.invoke(messages)
messages.append(ai_msg)

# Check the tool calls in the response
print(ai_msg.tool_calls)

# Step 2: Execute tools and collect results
for tool_call in ai_msg.tool_calls:
    # Execute the tool with the generated arguments
    tool_result = get_weather.invoke(tool_call)
    messages.append(tool_result)

# Step 3: Pass results back to model for final response
final_response = model_with_tools.invoke(messages)
final_response

[{'name': 'get_weather', 'args': {'location': 'Boston'}, 'id': '879b4233-901b-4bbb-af56-3771ca8d3a75', 'type': 'tool_call'}]

结构化输出

强制模型以特定结构响应。请参阅 Gemini API 文档了解更多。

from langchain_google_genai import ChatGoogleGenerativeAI
from pydantic import BaseModel
from typing import Literal


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


model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")
structured_model = model.with_structured_output(
    schema=Feedback.model_json_schema(), method="json_schema"
)

response = structured_model.invoke("The new UI is great!")
response["sentiment"]  # "positive"
response["summary"]  # "The user expresses positive..."

对于流式结构化输出，请合并字典而不是使用 +=:

stream = structured_model.stream("The interface is intuitive and beautiful!")
full = next(stream)
for chunk in stream:
    full.update(chunk)  # Merge dictionaries
print(full)  # Complete structured response
# -> {'sentiment': 'positive', 'summary': 'The user praises...'}

结构化输出方法

结构化输出支持两种方法：

- **method="json_schema" （默认）**：使用 Gemini 原生结构化输出。推荐用于更好的可靠性，因为它直接约束模型的生成过程，而不是依赖后处理工具调用。
- **method="function_calling"**：使用工具调用来提取结构化数据。

将结构化输出与 Google Search 结合

使用 with_structured_output(method="function_calling")时，不要在同一调用中传递其他工具（如 Google Search）。

要获取结构化输出 **和** 搜索 grounding 在单次调用中，请使用 .bind() 配合 response_mime_type 和 response_schema 而不是 with_structured_output:

from langchain_google_genai import ChatGoogleGenerativeAI
from pydantic import BaseModel


class MatchResult(BaseModel):
    winner: str
    final_match_score: str
    scorers: list[str]


llm = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

llm_with_search = llm.bind(
    tools=[{"google_search": {}}],
    response_mime_type="application/json",
    response_schema=MatchResult.model_json_schema(),
)

response = llm_with_search.invoke(
    "Search for details of the latest Euro championship final match."
)

这使用 Gemini 原生 JSON schema 模式来结构化输出，同时允许使用 Google Search 等工具进行 grounding——全部在单次 LLM 调用中完成。

令牌使用量追踪

从响应元数据中访问令牌使用信息。

from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

result = model.invoke("Explain the concept of prompt engineering in one sentence.")

print(result.content)
print("\nUsage Metadata:")
print(result.usage_metadata)

Prompt engineering is the art and science of crafting effective text prompts to elicit desired and accurate responses from large language models.

Usage Metadata:
{'input_tokens': 10, 'output_tokens': 24, 'total_tokens': 34, 'input_token_details': {'cache_read': 0}}

思考支持

某些 Gemini 模型支持可配置的思考深度。该参数取决于模型版本：

模型系列	参数	值
Gemini 3+	`thinking_level`	`"minimal"`, `"low"`, `"medium"`, `"high"` （Pro 默认）
Gemini 2.5	`thinking_budget`	`0` （关闭）， `-1` （动态），或正整数（令牌限制）

from langchain_google_genai import ChatGoogleGenerativeAI

# Gemini 3+: use thinking_level
llm = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    thinking_level="low",  # [!code highlight]
)

response = llm.invoke("How many O's are in Google?")

Gemini 2.5 模型： `thinking_budget`

对于 Gemini 2.5 模型，请使用 thinking_budget （整数令牌计数）代替：

- 设置为 0 可禁用思考（如果支持）
- 设置为 -1 用于动态思考（模型决定）
- 设置正整数以约束令牌使用

from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    thinking_budget=1024,  # [!code highlight]
)

查看模型思考

要查看思维模型的推理过程，请设置 include_thoughts=True:

from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
    model="gemini-3.5-flash",
    include_thoughts=True,  # [!code highlight]
)

response = llm.invoke("How many O's are in Google? How did you verify your answer?")
reasoning_tokens = response.usage_metadata["output_token_details"]["reasoning"]

print("Response:", response.content)
print("Reasoning tokens used:", reasoning_tokens)

Response: [{'type': 'thinking', 'thinking': '**Analyzing and Cou...'}, {'type': 'text', 'text': 'There a...', 'extras': {'signature': 'EroR...'}}]
Reasoning tokens used: 672

请参阅 Gemini API 文档了解更多关于思维的信息。

思维签名

思维签名是模型推理过程的加密表示。它们使 Gemini 能够在多轮对话中保持思维上下文，因为 API 是无状态的。

签名出现在 AIMessage responses: - **文本块**: extras.signature 中的 content 块内 - **工具调用**: additional_kwargs["__gemini_function_call_thought_signatures__"]

对于多轮对话，请将完整的 AIMessage 传回模型以保留签名。当您将 AIMessage 追加到消息列表时（如下面的工具调用示例所示）。

内置工具

Google Gemini 支持多种内置工具，可以按常规方式绑定到模型。

Google 搜索

请参阅 Gemini 文档了解更多详情。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    model_with_search = model.bind_tools([{"google_search": {}}]) # [!code highlight]
    response = model_with_search.invoke("When is the next total solar eclipse in US?")

    response.content_blocks

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    response = model.invoke(
        "When is the next total solar eclipse in US?",
        tools=[{"google_search": {}}], # [!code highlight]
    )

    response.content_blocks

[{'type': 'text',
  'text': 'The next total solar eclipse visible in the contiguous United States will occur on...',
  'annotations': [{'type': 'citation',
    'id': 'abc123',
    'url': '<url for source 1>',
    'title': '<source 1 title>',
    'start_index': 0,
    'end_index': 99,
    'cited_text': 'The next total solar eclipse...',
    'extras': {'google_ai_metadata': {'web_search_queries': ['next total solar eclipse in US'],
       'grounding_chunk_index': 0,
       'confidence_scores': []}}},
   ...

Google 地图

某些模型支持使用 Google 地图进行接地。地图接地将 Gemini 的生成能力与 Google 地图的当前真实位置数据相结合。这使得位置感知应用能够提供准确、地理位置特定的响应。请参阅 Gemini 文档了解更多详情。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

    model_with_maps = model.bind_tools([{"google_maps": {}}]) # [!code highlight]
    response = model_with_maps.invoke(
        "What are some good Italian restaurants near the Eiffel Tower in Paris?"
    )

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

    response = model.invoke(
        "What are some good Italian restaurants near the Eiffel Tower in Paris?",
        tools=[{"google_maps": {}}], # [!code highlight]
    )

响应将包含来自 Google 地图的位置信息接地元数据。

您可以选择使用 tool_config 配合 lat_lng提供特定的地理位置上下文。当您希望相对于特定地理点进行查询接地时，这非常有用。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

    # Provide location context (latitude and longitude)
    model_with_maps = model.bind_tools(
        [{"google_maps": {}}], # [!code highlight]
        tool_config={
            "retrieval_config": {  # Eiffel Tower
                "lat_lng": { # [!code highlight]
                    "latitude": 48.858844, # [!code highlight]
                    "longitude": 2.294351, # [!code highlight]
                } # [!code highlight]
            }
        },
    )

    response = model_with_maps.invoke(
        "What Italian restaurants are within a 5 minute walk from here?"
    )

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-pro")

    response = model.invoke(
        "What Italian restaurants are within a 5 minute walk from here?",
        tools=[{"google_maps": {}}], # [!code highlight]
        tool_config={
            "retrieval_config": {  # Eiffel Tower
                "lat_lng": { # [!code highlight]
                    "latitude": 48.858844, # [!code highlight]
                    "longitude": 2.294351, # [!code highlight]
                } # [!code highlight]
            }
        },
    )

URL 上下文

URL 上下文工具使模型能够访问和分析您在提示中提供的 URL 内容。这对于总结网页、从多个来源提取数据或回答有关在线内容的问题等任务非常有用。请参阅 Gemini 文档了解更多详情和限制。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")

    model_with_url_context = model.bind_tools([{"url_context": {}}]) # [!code highlight]
    response = model_with_url_context.invoke(
        "Summarize the content at https://docs.langchain.com"
    )

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")

    response = model.invoke(
        "Summarize the content at https://docs.langchain.com",
        tools=[{"url_context": {}}], # [!code highlight]
    )

代码执行

请参阅 Gemini 文档了解更多详情。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    model_with_code_interpreter = model.bind_tools([{"code_execution": {}}]) # [!code highlight]
    response = model_with_code_interpreter.invoke("Use Python to calculate 3^3.")

    response.content_blocks

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

    response = model.invoke(
        "Use Python to calculate 3^3.",
        tools=[{"code_execution": {}}], # [!code highlight]
    )

    response.content_blocks

[{'type': 'server_tool_call',
  'name': 'code_interpreter',
  'args': {'code': 'print(3**3)', 'language': },
  'id': '...'},
 {'type': 'server_tool_result',
  'tool_call_id': '',
  'status': 'success',
  'output': '27\n',
  'extras': {'block_type': 'code_execution_result',
   'outcome': }},
 {'type': 'text', 'text': 'The calculation of 3 to the power of 3 is 27.'}]

计算机使用

Gemini 2.5 计算机使用模型 (gemini-2.5-computer-use-preview-10-2025) 可以与浏览器环境交互，自动执行网页任务，如点击、输入和滚动。

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]
    model_with_computer = model.bind_tools([{"computer_use": {}}]) # [!code highlight]

    response = model_with_computer.invoke("Please navigate to example.com")

    response.content_blocks

    from langchain_google_genai import ChatGoogleGenerativeAI

    model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]

    response = model.invoke(
        "Please navigate to example.com",
        tools=[{"computer_use": {}}], # [!code highlight]
    )

    response.content_blocks

[{'type': 'tool_call',
  'id': '08a8b175-16ab-4861-8965-b736d5d4dd7e',
  'name': 'open_web_browser',
  'args': {}}]

您可以配置环境并排除特定的 UI 操作：

from langchain_google_genai import ChatGoogleGenerativeAI, Environment

model = ChatGoogleGenerativeAI(model="gemini-2.5-computer-use-preview-10-2025") # [!code highlight]

# Specify the environment (browser is default)
model_with_computer = model.bind_tools(
    [{"computer_use": {"environment": Environment.ENVIRONMENT_BROWSER}}] # [!code highlight]
)

# Exclude specific UI actions
model_with_computer = model.bind_tools(
    [
        {
            "computer_use": {
                "environment": Environment.ENVIRONMENT_BROWSER,
                "excludedPredefinedFunctions": [ # [!code highlight]
                    "drag_and_drop", # [!code highlight]
                    "key_combination", # [!code highlight]
                ], # [!code highlight]
            }
        }
    ]
)

response = model_with_computer.invoke("Search for Python tutorials")

模型返回 UI 操作的函数调用（例如 click_at, type_text_at, scroll），并带有规范化坐标。您需要在浏览器自动化框架中实现这些操作的实际执行。

安全设置

Gemini 模型具有可覆盖的默认安全设置。如果您收到大量 'Safety Warnings' 来自您的模型，可以尝试调整模型的 safety_settings 属性。例如，要关闭对危险内容的安全阻止，可以按如下方式构建 LLM：

from langchain_google_genai import (
    ChatGoogleGenerativeAI,
    HarmBlockThreshold,
    HarmCategory,
)

llm = ChatGoogleGenerativeAI(
        model="gemini-3.5-flash",
        safety_settings={
        HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_NONE,
    },
)

有关可用的类别和阈值枚举，请参阅 Google 的安全设置指南.

上下文缓存

上下文缓存允许您存储和重用内容（例如 PDF、图片）以加快处理速度。 cached_content 参数接受通过 Google Generative AI API 创建的缓存名称。

Single file example

这会缓存单个文件并对其进行查询。

from google import genai
from google.genai import types
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI

client = genai.Client()

# Upload file
file = client.files.upload(file="path/to/your/file")
while file.state.name == "PROCESSING":
    time.sleep(2)
    file = client.files.get(name=file.name)

# Create cache
model = "gemini-3.5-flash"
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
        display_name="Cached Content",
        system_instruction=(
            "You are an expert content analyzer, and your job is to answer "
            "the user's query based on the file you have access to."
        ),
        contents=[file],
        ttl="300s",
    ),
)

# Query with LangChain
llm = ChatGoogleGenerativeAI(
    model=model,
    cached_content=cache.name,
)
message = HumanMessage(content="Summarize the main points of the content.")
llm.invoke([message])

Multiple files example

这会缓存两个文件并使用 Part 一起查询它们。

from google import genai
from google.genai.types import CreateCachedContentConfig, Content, Part
from langchain.messages import HumanMessage
from langchain_google_genai import ChatGoogleGenerativeAI

client = genai.Client()

# Upload files
file_1 = client.files.upload(file="./file1")
while file_1.state.name == "PROCESSING":
    time.sleep(2)
    file_1 = client.files.get(name=file_1.name)

file_2 = client.files.upload(file="./file2")
while file_2.state.name == "PROCESSING":
    time.sleep(2)
    file_2 = client.files.get(name=file_2.name)

# Create cache with multiple files
contents = [
    Content(
        role="user",
        parts=[
            Part.from_uri(file_uri=file_1.uri, mime_type=file_1.mime_type),
            Part.from_uri(file_uri=file_2.uri, mime_type=file_2.mime_type),
        ],
    )
]
model = "gemini-3.5-flash"
cache = client.caches.create(
    model=model,
    config=CreateCachedContentConfig(
        display_name="Cached Contents",
        system_instruction=(
            "You are an expert content analyzer, and your job is to answer "
            "the user's query based on the files you have access to."
        ),
        contents=contents,
        ttl="300s",
    ),
)

# Query with LangChain
llm = ChatGoogleGenerativeAI(
    model=model,
    cached_content=cache.name,
)
message = HumanMessage(
    content="Provide a summary of the key information across both files."
)
llm.invoke([message])

请参阅 Gemini API 文档中的上下文缓存了解更多信息。

响应元数据

从模型响应访问响应元数据。

from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(model="gemini-3.5-flash")

response = llm.invoke("Hello!")
response.response_metadata

{'prompt_feedback': {'block_reason': 0, 'safety_ratings': []},
 'finish_reason': 'STOP',
 'model_name': 'gemini-3.5-flash',
 'safety_ratings': [],
 'model_provider': 'google_genai'}

API 参考

有关所有功能和配置选项的详细文档，请访问 ChatGoogleGenerativeAI API 参考。

概述

集成详情

模型特性

设置

安装

凭证

后端选择

Gemini Developer API

Vertex AI with API key

Vertex AI with credentials

环境变量

实例化

Gemini Developer API

Vertex AI

代理配置

自定义端点和请求头

调用

多模态用法

支持的输入方法

文件上传

图像输入

PDF 输入

音频输入

视频输入

图像生成

音频生成

工具调用

结构化输出

结构化输出方法

将结构化输出与 Google Search 结合

令牌使用量追踪

思考支持

Gemini 2.5 模型： thinking_budget

查看模型思考

思维签名

内置工具

Google 搜索

Google 地图

URL 上下文

代码执行

计算机使用

安全设置

上下文缓存

Single file example

Multiple files example

响应元数据

API 参考

Gemini 2.5 模型： `thinking_budget`