文档API 参考📓 教程🧑‍🍳 食谱🤝 集成💜 Discord🎨 Studio
API 参考

Google GenAI

Google GenAI 集成，用于 Haystack

模块 haystack_integrations.components.generators.google_genai.chat.chat_generator

GoogleGenAIChatGenerator

一个组件，用于通过 Google Gen AI SDK 使用 Google 的 Gemini 模型生成聊天补全。

支持 gemini-2.0-flash 等模型以及其他 Gemini 变体。对于 Gemini 2.5 系列模型，可以通过generation_kwargs={"thinking_budget": value}.

启用思考功能（Gemini 2.5 系列）

  • 推理透明度：模型可以展示其推理过程
  • 思考签名：在与工具的多轮对话中保持思考上下文
  • 可配置思考预算：控制推理的 token 分配

配置思考行为

  • thinking_budget: -1：动态分配（默认）
  • thinking_budget: 0：禁用思考（仅限 Flash/Flash-Lite）
  • thinking_budget: N：设置显式 token 预算

多轮思考与思考签名

当存在工具时，Gemini 使用思考签名——加密的“保存状态”，可在多轮对话中保持上下文。在聊天历史中包含先前的助手响应以保留上下文。

身份验证

Gemini 开发者 API：设置GOOGLE_API_KEY 或GEMINI_API_KEY 环境变量 Vertex AI：使用api="vertex" 结合应用默认凭证或 API 密钥

身份验证示例

1. Gemini 开发者 API（API 密钥身份验证）

from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator

# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
chat_generator = GoogleGenAIChatGenerator(model="gemini-2.0-flash")

2. Vertex AI（应用默认凭证）

from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator

# Using Application Default Credentials (requires gcloud auth setup)
chat_generator = GoogleGenAIChatGenerator(
    api="vertex",
    vertex_ai_project="my-project",
    vertex_ai_location="us-central1",
    model="gemini-2.0-flash"
)

3. Vertex AI（API 密钥身份验证）

from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator

# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
chat_generator = GoogleGenAIChatGenerator(
    api="vertex",
    model="gemini-2.0-flash"
)

使用示例

from haystack.dataclasses.chat_message import ChatMessage
from haystack.tools import Tool, Toolset
from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator

# Initialize the chat generator with thinking support
chat_generator = GoogleGenAIChatGenerator(
    model="gemini-2.5-flash",
    generation_kwargs={"thinking_budget": 1024}  # Enable thinking with 1024 token budget
)

# Generate a response
messages = [ChatMessage.from_user("Tell me about the future of AI")]
response = chat_generator.run(messages=messages)
print(response["replies"][0].text)

# Access reasoning content if available
message = response["replies"][0]
if message.reasonings:
    for reasoning in message.reasonings:
        print("Reasoning:", reasoning.reasoning_text)

# Tool usage example with thinking
def weather_function(city: str):
    return f"The weather in {city} is sunny and 25°C"

weather_tool = Tool(
    name="weather",
    description="Get weather information for a city",
    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    function=weather_function
)

# Can use either List[Tool] or Toolset
chat_generator_with_tools = GoogleGenAIChatGenerator(
    model="gemini-2.5-flash",
    tools=[weather_tool],  # or tools=Toolset([weather_tool])
    generation_kwargs={"thinking_budget": -1}  # Dynamic thinking allocation
)

messages = [ChatMessage.from_user("What's the weather in Paris?")]
response = chat_generator_with_tools.run(messages=messages)

GoogleGenAIChatGenerator.__init__

def __init__(*,
             api_key: Secret = Secret.from_env_var(
                 ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False),
             api: Literal["gemini", "vertex"] = "gemini",
             vertex_ai_project: Optional[str] = None,
             vertex_ai_location: Optional[str] = None,
             model: str = "gemini-2.0-flash",
             generation_kwargs: Optional[Dict[str, Any]] = None,
             safety_settings: Optional[List[Dict[str, Any]]] = None,
             streaming_callback: Optional[StreamingCallbackT] = None,
             tools: Optional[Union[List[Tool], Toolset]] = None)

初始化一个 GoogleGenAIChatGenerator 实例。

参数:

  • api_key：Google API 密钥，默认为GOOGLE_API_KEY 和GEMINI_API_KEY 环境变量。如果使用 Vertex AI 并配合应用默认凭证，则不需要。获取 Gemini API 密钥请访问 https://aistudio.google.com/app/apikey。获取 Vertex AI API 密钥请访问 https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys。
  • api：要使用的 API。可以是 "gemini"（用于 Gemini 开发者 API）或 "vertex"（用于 Vertex AI）。
  • vertex_ai_project：Vertex AI 的 Google Cloud 项目 ID。在使用 Vertex AI 和应用默认凭证时必需。
  • vertex_ai_location：Vertex AI 的 Google Cloud 位置（例如 "us-central1"、"europe-west1"）。在使用 Vertex AI 和应用默认凭证时必需。
  • model：要使用的模型名称（例如 "gemini-2.0-flash"）
  • generation_kwargs：用于生成的配置（temperature、max_tokens 等）。对于 Gemini 2.5 系列，支持thinking_budget 来配置思考行为
  • thinking_budget：int，控制思考 token 分配
    • -1：动态（大多数模型的默认值）
    • 0：禁用思考（仅限 Flash/Flash-Lite）
    • 正整数：设置显式预算
  • safety_settings：用于内容过滤的安全设置
  • streaming_callback: 当从流中接收到新 token 时调用的回调函数。
  • tools：模型可以使用的一系列 Tool 对象或 Toolset。每个工具都应有一个唯一的名称。

GoogleGenAIChatGenerator.to_dict

def to_dict() -> Dict[str, Any]

将组件序列化为字典。

返回值:

包含序列化数据的字典。

GoogleGenAIChatGenerator.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAIChatGenerator"

从字典反序列化组件。

参数:

  • data: 要反序列化的字典。

返回值:

反序列化后的组件。

GoogleGenAIChatGenerator.run

@component.output_types(replies=List[ChatMessage])
def run(messages: List[ChatMessage],
        generation_kwargs: Optional[Dict[str, Any]] = None,
        safety_settings: Optional[List[Dict[str, Any]]] = None,
        streaming_callback: Optional[StreamingCallbackT] = None,
        tools: Optional[Union[List[Tool], Toolset]] = None) -> Dict[str, Any]

在给定的输入数据上运行 Google Gen AI 聊天生成器。

参数:

  • messages: 一个 ChatMessage 实例列表，表示输入消息。
  • generation_kwargs：用于生成的配置。如果提供，它将覆盖默认配置。支持thinking_budget 用于 Gemini 2.5 系列的思考配置。
  • safety_settings：用于内容过滤的安全设置。如果提供，它将覆盖默认设置。
  • streaming_callback: 当从流中接收到新 token 时调用的回调函数。
  • tools：模型可以使用的一系列 Tool 对象或 Toolset。如果提供，它将覆盖初始化时设置的工具。

引发:

  • RuntimeError：如果在 Google Gen AI 聊天生成过程中发生错误。
  • ValueError：如果 ChatMessage 不包含 TextContent、ToolCall 或 ToolCallResult 中的至少一项，或者 ChatMessage 中的 role 不是 User、System 或 Assistant。

返回值:

包含以下键的字典

  • replies：一个包含生成的 ChatMessage 响应的列表。

GoogleGenAIChatGenerator.run_async

@component.output_types(replies=List[ChatMessage])
async def run_async(
        messages: List[ChatMessage],
        generation_kwargs: Optional[Dict[str, Any]] = None,
        safety_settings: Optional[List[Dict[str, Any]]] = None,
        streaming_callback: Optional[StreamingCallbackT] = None,
        tools: Optional[Union[List[Tool], Toolset]] = None) -> Dict[str, Any]

run 方法的异步版本。在给定的输入数据上运行 Google Gen AI 聊天生成器。

参数:

  • messages: 一个 ChatMessage 实例列表，表示输入消息。
  • generation_kwargs：用于生成的配置。如果提供，它将覆盖默认配置。支持thinking_budget 用于 Gemini 2.5 系列的思考配置。有关可能的取值，请参阅 https://ai.google.dev/gemini-api/docs/thinking。
  • safety_settings：用于内容过滤的安全设置。如果提供，它将覆盖默认设置。
  • streaming_callback: 当从流中接收到新 token 时调用的回调函数。
  • tools：模型可以使用的一系列 Tool 对象或 Toolset。如果提供，它将覆盖初始化时设置的工具。

引发:

  • RuntimeError：如果在异步 Google Gen AI 聊天生成过程中发生错误。
  • ValueError：如果 ChatMessage 不包含 TextContent、ToolCall 或 ToolCallResult 中的至少一项，或者 ChatMessage 中的 role 不是 User、System 或 Assistant。

返回值:

包含以下键的字典

  • replies：一个包含生成的 ChatMessage 响应的列表。

模块 haystack_integrations.components.embedders.google_genai.document_embedder

GoogleGenAIDocumentEmbedder

使用 Google AI 模型计算文档嵌入。

身份验证示例

1. Gemini 开发者 API（API 密钥身份验证）

from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder

# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
document_embedder = GoogleGenAIDocumentEmbedder(model="text-embedding-004")

**2. Vertex AI (Application Default Credentials)**
```python
from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder

__Using Application Default Credentials (requires gcloud auth setup)__

document_embedder = GoogleGenAIDocumentEmbedder(
    api="vertex",
    vertex_ai_project="my-project",
    vertex_ai_location="us-central1",
    model="text-embedding-004"
)

3. Vertex AI（API 密钥身份验证）

from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder

__export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)__

document_embedder = GoogleGenAIDocumentEmbedder(
    api="vertex",
    model="text-embedding-004"
)

使用示例

from haystack import Document
from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder

doc = Document(content="I love pizza!")

document_embedder = GoogleGenAIDocumentEmbedder()

result = document_embedder.run([doc])
print(result['documents'][0].embedding)

__[0.017020374536514282, -0.023255806416273117, ...]__

GoogleGenAIDocumentEmbedder.__init__

def __init__(*,
             api_key: Secret = Secret.from_env_var(
                 ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False),
             api: Literal["gemini", "vertex"] = "gemini",
             vertex_ai_project: Optional[str] = None,
             vertex_ai_location: Optional[str] = None,
             model: str = "text-embedding-004",
             prefix: str = "",
             suffix: str = "",
             batch_size: int = 32,
             progress_bar: bool = True,
             meta_fields_to_embed: Optional[List[str]] = None,
             embedding_separator: str = "\n",
             config: Optional[Dict[str, Any]] = None) -> None

创建一个 GoogleGenAIDocumentEmbedder 组件。

参数:

  • api_key：Google API 密钥，默认为GOOGLE_API_KEY 和GEMINI_API_KEY 环境变量。如果使用 Vertex AI 并配合应用默认凭证，则不需要。获取 Gemini API 密钥请访问 https://aistudio.google.com/app/apikey。获取 Vertex AI API 密钥请访问 https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys。
  • api：要使用的 API。可以是 "gemini"（用于 Gemini 开发者 API）或 "vertex"（用于 Vertex AI）。
  • vertex_ai_project：Vertex AI 的 Google Cloud 项目 ID。在使用 Vertex AI 和应用默认凭证时必需。
  • vertex_ai_location：Vertex AI 的 Google Cloud 位置（例如 "us-central1"、"europe-west1"）。在使用 Vertex AI 和应用默认凭证时必需。
  • model：用于计算嵌入的模型名称。默认模型是text-embedding-ada-002.
  • prefix: 添加到每个文本开头的字符串。
  • suffix: 添加到每个文本末尾的字符串。
  • batch_size：一次嵌入的文档数量。
  • progress_bar: 如果True，则运行时显示进度条。
  • meta_fields_to_embed: 要与文档文本一起嵌入的元数据字段列表。
  • embedding_separator: 用于将元数据字段连接到文档文本的分隔符。
  • config：一个字典，包含用于配置嵌入内容配置的关键字参数types.EmbedContentConfig。如果未指定，则默认为 {"task_type": "SEMANTIC_SIMILARITY"}。有关更多信息，请参阅 Google AI 任务类型。

GoogleGenAIDocumentEmbedder.to_dict

def to_dict() -> Dict[str, Any]

将组件序列化为字典。

返回值:

包含序列化数据的字典。

GoogleGenAIDocumentEmbedder.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAIDocumentEmbedder"

从字典反序列化组件。

参数:

  • data: 要反序列化的字典。

返回值:

反序列化后的组件。

GoogleGenAIDocumentEmbedder.run

@component.output_types(documents=List[Document], meta=Dict[str, Any])
def run(
    documents: List[Document]
) -> Union[Dict[str, List[Document]], Dict[str, Any]]

嵌入一系列文档。

参数:

  • documents：要嵌入的文档列表。

返回值:

包含以下键的字典

  • documents：包含嵌入的文档列表。
  • meta：有关模型使用情况的信息。

GoogleGenAIDocumentEmbedder.run_async

@component.output_types(documents=List[Document], meta=Dict[str, Any])
async def run_async(
    documents: List[Document]
) -> Union[Dict[str, List[Document]], Dict[str, Any]]

异步嵌入一系列文档。

参数:

  • documents：要嵌入的文档列表。

返回值:

包含以下键的字典

  • documents：包含嵌入的文档列表。
  • meta：有关模型使用情况的信息。

模块 haystack_integrations.components.embedders.google_genai.text_embedder

GoogleGenAITextEmbedder

使用 Google AI 模型嵌入字符串。

您可以使用它来嵌入用户查询并将查询发送到嵌入检索器。

身份验证示例

1. Gemini 开发者 API（API 密钥身份验证）

from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder

# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)
text_embedder = GoogleGenAITextEmbedder(model="text-embedding-004")

**2. Vertex AI (Application Default Credentials)**
```python
from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder

__Using Application Default Credentials (requires gcloud auth setup)__

text_embedder = GoogleGenAITextEmbedder(
    api="vertex",
    vertex_ai_project="my-project",
    vertex_ai_location="us-central1",
    model="text-embedding-004"
)

3. Vertex AI（API 密钥身份验证）

from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder

__export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)__

text_embedder = GoogleGenAITextEmbedder(
    api="vertex",
    model="text-embedding-004"
)

使用示例

from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder

text_to_embed = "I love pizza!"

text_embedder = GoogleGenAITextEmbedder()

print(text_embedder.run(text_to_embed))

__{'embedding': [0.017020374536514282, -0.023255806416273117, ...],__

__'meta': {'model': 'text-embedding-004-v2',__

__         'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}__

GoogleGenAITextEmbedder.__init__

def __init__(*,
             api_key: Secret = Secret.from_env_var(
                 ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False),
             api: Literal["gemini", "vertex"] = "gemini",
             vertex_ai_project: Optional[str] = None,
             vertex_ai_location: Optional[str] = None,
             model: str = "text-embedding-004",
             prefix: str = "",
             suffix: str = "",
             config: Optional[Dict[str, Any]] = None) -> None

创建一个 GoogleGenAITextEmbedder 组件。

参数:

  • api_key：Google API 密钥，默认为GOOGLE_API_KEY 和GEMINI_API_KEY 环境变量。如果使用 Vertex AI 并配合应用默认凭证，则不需要。获取 Gemini API 密钥请访问 https://aistudio.google.com/app/apikey。获取 Vertex AI API 密钥请访问 https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys。
  • api：要使用的 API。可以是 "gemini"（用于 Gemini 开发者 API）或 "vertex"（用于 Vertex AI）。
  • vertex_ai_project：Vertex AI 的 Google Cloud 项目 ID。在使用 Vertex AI 和应用默认凭证时必需。
  • vertex_ai_location：Vertex AI 的 Google Cloud 位置（例如 "us-central1"、"europe-west1"）。在使用 Vertex AI 和应用默认凭证时必需。
  • model：用于计算嵌入的模型名称。默认模型是text-embedding-004.
  • prefix：添加到每个待嵌入文本开头的字符串。
  • suffix：添加到每个待嵌入文本末尾的字符串。
  • config：一个字典，包含用于配置嵌入内容配置的关键字参数types.EmbedContentConfig。如果未指定，则默认为 {"task_type": "SEMANTIC_SIMILARITY"}。有关更多信息，请参阅 Google AI 任务类型。

GoogleGenAITextEmbedder.to_dict

def to_dict() -> Dict[str, Any]

将组件序列化为字典。

返回值:

包含序列化数据的字典。

GoogleGenAITextEmbedder.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAITextEmbedder"

从字典反序列化组件。

参数:

  • data: 要反序列化的字典。

返回值:

反序列化后的组件。

GoogleGenAITextEmbedder.run

@component.output_types(embedding=List[float], meta=Dict[str, Any])
def run(text: str) -> Union[Dict[str, List[float]], Dict[str, Any]]

嵌入单个字符串。

参数:

  • text：要嵌入的文本。

返回值:

包含以下键的字典

  • embedding：输入文本的嵌入。
  • meta：有关模型使用情况的信息。

GoogleGenAITextEmbedder.run_async

@component.output_types(embedding=List[float], meta=Dict[str, Any])
async def run_async(
        text: str) -> Union[Dict[str, List[float]], Dict[str, Any]]

异步嵌入单个字符串。

这是run 方法。它具有相同的参数和返回值，但可以在异步代码中与await 一起使用。

参数:

  • text：要嵌入的文本。

返回值:

包含以下键的字典

  • embedding：输入文本的嵌入。
  • meta：有关模型使用情况的信息。