Haystack 集成 Google GenAI从 Gemini 文本/多模态嵌入到带思考能力的 ChatGenerator 与 Token 计数完整实战指南【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本篇技术指南以 Haystack Google GenAI 集成参考文档 为核心骨架系统讲解google-genai-haystack集成在 Haystack 中的全部组件三类 Embedder文本文档、多模态文档、查询文本、支持思考能力与工具调用的GoogleGenAIChatGenerator以及基于countTokens接口的GoogleGenAITokenCounter。读完本文你将掌握从三种认证方式的选择、嵌入参数调优、多模态文件嵌入的路径安全配置到组装完整 RAG/Agent 管线的全部实战细节。一、集成概览一套包五类能力google-genai-haystack是基于 Google 官方 Gen AI SDKpython-genai构建的 Haystack 集成包兼容 Gemini Developer API 与 Vertex AI 两套后端。参考文档将其能力划分为五个模块全部以haystack_integrations命名空间暴露模块类职责components.embedders.google_genai.document_embedderGoogleGenAIDocumentEmbedder用 Google AI 模型计算文本文档的嵌入向量components.embedders.google_genai.multimodal_document_embedderGoogleGenAIMultimodalDocumentEmbedder计算非文本文档图片、PDF、视频、音频的嵌入映射到同一向量空间components.embedders.google_genai.text_embedderGoogleGenAITextEmbedder将字符串如用户查询编码为向量供嵌入检索器使用components.generators.google_genai.chat.chat_generatorGoogleGenAIChatGenerator基于 Gemini 模型的聊天补全支持思考thinking、工具、结构化输出与多模态输入token_counters.google_genai.token_counterGoogleGenAITokenCounter调用 Google 官方countTokens接口精确统计 Gemini 输入 token安装方式统一为pip install google-genai-haystack从组件关系上看三类 Embedder 负责把文档与查询映射到同一向量空间这是向量检索成立的前提ChatGenerator 负责生成环节TokenCounter 则服务于 Agent 上下文管理与成本预估。配套的分组件使用指南可在 embedders 文档目录 与 generators 文档目录 中找到。二、认证方式三套配置覆盖两种后端参考文档中所有组件都共享同一套认证设计api_key参数默认从GOOGLE_API_KEY或GEMINI_API_KEY环境变量读取strictFalse两个变量都未设置时才报错并通过api参数在geminiGemini Developer API与vertexVertex AI之间切换。三种写法如下以 DocumentEmbedder 为例其余组件完全同构1. Gemini Developer APIAPI Key 认证from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) document_embedder GoogleGenAIDocumentEmbedder(modelgemini-embedding-001)2. Vertex AIApplication Default Credentialsfrom haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # Using Application Default Credentials (requires gcloud auth setup) document_embedder GoogleGenAIDocumentEmbedder( apivertex, vertex_ai_projectmy-project, vertex_ai_locationus-central1, modelgemini-embedding-001 )3. Vertex AIAPI Key 认证from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) document_embedder GoogleGenAIDocumentEmbedder( apivertex, modelgemini-embedding-001 )认证机制与 Secret 管理这套设计背后的核心抽象是 Haystack 的Secret类实现见 haystack/utils/auth.pySecret.from_env_var([GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse)按顺序解析第一个已设置的环境变量strictFalse表示变量缺失时不抛异常留给运行期报错。Secret.from_token(your-api-key)直接把密钥写进初始化参数文档明确标注 token 型 Secret 不可序列化源码说明适合交互式脚本生产环境仍推荐环境变量方式。Vertex AI 的 ADCApplication Default Credentials模式不需要 API Key但必须显式传入vertex_ai_project与vertex_ai_location如us-central1、europe-west1并提前完成 gcloud 认证配置。三、GoogleGenAIDocumentEmbedder文本文档批量向量化该组件使用 Google AI 模型计算文档嵌入输出会被写入每个Document的embedding字段——这正是 Document 数据类 中embedding: list[float]字段的用途。它通常位于索引管线的DocumentWriter之前。完整初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-embedding-001, prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None参数详解参数类型默认值说明api_keySecret环境变量GOOGLE_API_KEY/GEMINI_API_KEYVertex AI 配合 ADC 时无需提供apiLiteral[gemini, vertex]gemini选择 Gemini Developer API 或 Vertex AIvertex_ai_projectstr \| NoneNoneVertex AI ADC 模式必需GCP 项目 IDvertex_ai_locationstr \| NoneNoneVertex AI ADC 模式必需如us-central1modelstrgemini-embedding-001嵌入模型名prefixstr文本前附加字符串可用于为gemini-embedding-2指定任务类型task typesuffixstr文本末尾附加字符串batch_sizeint32单次批量嵌入的文档数progress_barboolTrue运行是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要随正文一起嵌入的元数据字段列表embedding_separatorstr\n拼接元数据与正文时使用的分隔符configdict[str, Any] \| NoneNone透传给 Google SDKEmbedContentConfig的参数字典注意在config中指定 task type 对gemini-embedding-2不生效timeoutfloat \| NoneNone底层 Google GenAI 客户端网络请求超时秒max_retriesint \| NoneNone底层客户端最大重试次数使用示例from haystack import Document from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder doc Document(contentI love pizza!) document_embedder GoogleGenAIDocumentEmbedder() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run(documents)返回字典含两个键documents已携带嵌入向量的文档列表与meta模型用量信息如 token 数。进阶把语义化元数据一并嵌入文档自带元数据如果语义鲜明可以一并编码以提升检索质量参考 GoogleGenAIDocumentEmbedder 组件指南from haystack import Document from haystack.utils import Secret from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder doc Document(contentsome text, meta{title: relevant title, page number: 18}) embedder GoogleGenAIDocumentEmbedder( api_keySecret.from_token(your-api-key), meta_fields_to_embed[title], ) docs_w_embeddings embedder.run(documents[doc])[documents]拼接规则为content embedding_separator meta 字段值默认分隔符是换行符\n可通过embedding_separator调整。四、GoogleGenAITextEmbedder查询字符串向量化与 DocumentEmbedder 对应GoogleGenAITextEmbedder使用 Google AI 模型嵌入字符串典型场景是查询侧把用户问题编码后交给嵌入检索器Embedding Retriever做相似度检索。初始化签名与差异点__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-embedding-001, prefix: str , suffix: str , config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None它没有batch_size/progress_bar/meta_fields_to_embed等批处理参数因为每次只嵌一个字符串其余参数语义与 DocumentEmbedder 完全一致。使用示例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: gemini-embedding-001-v2, # usage: {prompt_tokens: 4, total_tokens: 4}}}run(text)返回embedding输入文本的向量与meta模型名与 token 用量。注意meta中的模型名会带上服务端实际使用的版本后缀如gemini-embedding-001-v2可作为确认所用模型版本的依据。五、GoogleGenAIMultimodalDocumentEmbedder图片/PDF/视频/音频统一嵌入该组件是文档中唯一面向非文本内容的嵌入器支持图片、PDF、视频与音频文件并把它们映射到同一个向量空间从而可以与文本嵌入直接做相似度比较。文本文档请用GoogleGenAIDocumentEmbedder查询字符串请用GoogleGenAITextEmbedder。初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, file_path_meta_field: str file_path, root_path: str | None None, image_size: tuple[int, int] | None None, model: str gemini-embedding-2, batch_size: int 6, progress_bar: bool True, config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None参数详解参数类型默认值说明file_path_meta_fieldstrfile_pathDocument 元数据中存放待嵌入文件路径的字段名root_pathstr \| NoneNone文件根目录设置后元数据中的路径将相对该目录解析并保证不越出该目录为None时路径按绝对路径处理且不做越界检查。若元数据可能受不可信输入影响务必设置专用数据目录以拒绝路径穿越image_sizetuple[int, int] \| NoneNone仅作用于图片与 PDF 页等比缩放至指定宽, 高范围内降低文件体积、内存占用与传输耗时适合有分辨率限制的模型modelstrgemini-embedding-2嵌入模型名参考文档示例亦用gemini-embedding-2-previewbatch_sizeint6单批嵌入文档数最大批大小随输入类型变化configdict[str, Any] \| NoneNone嵌入内容配置例如设置输出维度{output_dimensionality: 768}其余api_key/api/vertex_ai_project/vertex_ai_location/progress_bar/timeout/max_retries语义与前两类组件相同。使用示例from haystack import Document from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder doc Document(contentNone, meta{file_path: path/to/image.jpg}) document_embedder GoogleGenAIMultimodalDocumentEmbedder() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]注意Document的content为None文件路径放在meta[file_path]可通过file_path_meta_field改名。这与 Document 数据类 中content可为 None、meta承载扩展信息的设计一致。异常语义值得注意的健壮性设计参考文档为run与run_async明确列出了三类异常便于调用方捕获处理TypeError输入不是Document列表ValueError文档缺失文件路径元数据字段、文件路径越出root_path、或 MIME 类型不受支持RuntimeError部分文档转换失败。其中root_path的路径越界校验是安全相关的关键设计——当文档元数据可能来自不可信来源如外部导入的文档集时设置root_path可有效防止路径遍历攻击。六、GoogleGenAIChatGeneratorGemini 对话生成与思考能力GoogleGenAIChatGenerator通过 Google Gen AI SDK 完成 Gemini 对话补全是集成中功能最丰富的组件支持思考thinking、工具调用、结构化输出、流式与多模态输入。支持的模型SUPPORTED_MODELS: list[str] [ gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-3.1-flash-lite-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, ]该列表是非穷尽的参考文档原文即注明 A non-exhaustive list更完整的模型 ID 以 Google 官方模型文档为准。思考能力Thinking Support针对 Gemini 2.5 与 Gemini 3 系列模型组件开放了思考配置推理透明化模型可以展示推理过程思维签名Thought Signatures多轮对话配合工具时通过加密的保存状态维持跨轮次的思维上下文——因此使用工具时应把之前的助手回复保留在聊天历史中可配置思考预算精确控制分配给推理的 token。通过generation_kwargs{thinking_budget: value}配置thinking_budget含义-1动态分配默认0禁用思考仅 Flash / Flash-Lite 系列正整数N显式设置 token 预算Gemini 3 系列及更新模型还支持thinking_level思考深度可选minimal接近无思考仅复杂编码任务会有极少量思考延迟最低、low适合简单指令遵循、对话与高吞吐场景、medium多数任务的均衡档、high默认动态档推理最深但首 token 延迟显著增大。初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-3.7-flash, generation_kwargs: dict[str, Any] | None None, safety_settings: list[dict[str, Any]] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, timeout: float | None None, max_retries: int | None None ) - None关键参数generation_kwargs承载 temperature、max_tokens 以及上文的thinking_budget/thinking_levelsafety_settings控制内容过滤streaming_callback在收到新 token 时被调用tools接受Tool和/或Toolset的列表或单个Toolset每个工具名须唯一timeout/max_retries未设置时采用 Google Gen AI 客户端默认值。使用示例开启思考并读取推理内容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( modelgemini-3.7-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(messagesmessages) 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)replies中每条ChatMessage的reasonings字段承载推理内容——该字段在 Haystack 中由 ReasoningContent 内容类型 表示其中reasoning_text即推理文本。使用示例带思考的工具调用# Tool usage example with thinking def weather_function(city: str): return fThe weather in {city} is sunny and 25°C weather_tool Tool( nameweather, descriptionGet weather information for a city, parameters{type: object, properties: {city: {type: string}}, required: [city]}, functionweather_function ) # Can use either List[Tool] or Toolset chat_generator_with_tools GoogleGenAIChatGenerator( modelgemini-3.7-flash, tools[weather_tool], # or toolsToolset([weather_tool]) generation_kwargs{thinking_budget: -1} # Dynamic thinking allocation ) messages [ChatMessage.from_user(Whats the weather in Paris?)] response chat_generator_with_tools.run(messagesmessages)组件指南googlegenaichatgenerator.mdx进一步说明tools参数支持混用单个工具列表、单个 Toolset、以及多个 Toolset 独立工具的混合列表便于把相关工具逻辑分组。工具调用后的结果回合通常由 Haystack 的ToolInvoker执行见 haystack/components/tools 目录。使用示例结构化输出from pydantic import BaseModel from haystack.dataclasses.chat_message import ChatMessage from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator class City(BaseModel): name: str country: str population: int chat_generator GoogleGenAIChatGenerator( modelgemini-3.7-flash, generation_kwargs{response_format: City} ) messages [ChatMessage.from_user(Tell me about Paris)] response chat_generator.run(messagesmessages) print(response[replies][0].text) # JSON output matching the City schema通过generation_kwargs{response_format: Pydantic 模型}直接约束输出为符合 schema 的 JSON。使用示例ChatMessage 内嵌 FileContent 多模态输入from haystack.dataclasses import ChatMessage, FileContent from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator file_content FileContent.from_url(https://arxiv.org/pdf/2309.08632) chat_message ChatMessage.from_user(content_parts[file_content, Summarize this paper in 100 words.]) chat_generator GoogleGenAIChatGenerator() response chat_generator.run(messages[chat_message])FileContent是 haystack/dataclasses/file_content.py 中定义的内容类型承载 base64 数据与 MIME 类型from_url通过内置的LinkContentFetcher下载文件并自动推断 MIME 类型实现见 file_content.py。图片场景还可使用ImageContent.from_file_pathimage_content.py它支持缩放与格式校验。run 方法签名与覆盖规则run( messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, safety_settings: list[dict[str, Any]] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, ) - dict[str, Any]要点messages也接受裸字符串会自动包装成一条 user 角色的ChatMessagegeneration_kwargs按key 粒度与初始化时的配置合并run 传入的 key 优先仅初始化设置的 key 保留safety_settings、tools传入后会覆盖初始化时设置的对应值返回值仅含replies生成的ChatMessage列表异常RuntimeError生成过程出错ValueError某条ChatMessage不包含TextContent/ToolCall/ToolCallResult中的任何一种或角色不是 User/System/Assistant。角色体系定义见 chat_message.py 中的 ChatRole。run_async为完全对应的异步版本支持await。七、GoogleGenAITokenCounter官方接口的精确 Token 计数GoogleGenAITokenCounter调用 Google Gen AI SDK 的countTokens端点统计 Gemini 输入 token。与本地估算类计数器不同它把消息原样发送到官方端点因此计数包含 Gemini 对消息施加的模型专属格式化formatting。输入按GoogleGenAIChatGenerator的发送方式装配首条 system 消息作为系统指令其余消息作为请求内容。初始化签名__init__( model: str, *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, timeout: float | None None, max_retries: int | None None ) - Nonemodel是必填位置参数token 计数与模型相关应传入你实际用于生成的同一模型。使用示例from haystack.dataclasses import ChatMessage from haystack_integrations.token_counters.google_genai import GoogleGenAITokenCounter counter GoogleGenAITokenCounter(gemini-3.7-flash) messages [ChatMessage.from_user(Hello, how are you?)] token_count counter.count(messages) print(fToken count: {token_count})count(messages, toolsNone)返回int无可测内容时返回0传入tools时其 schema 也会计入 token。后端差异系统指令与工具的支持边界这是参考文档明确强调的重要坑点Google Gen AI SDK 只有在客户端指向Vertex AI时才接受在countTokens上传系统指令与工具 schema在Gemini Developer API上首条 system 消息会被当作 user 轮次统计是近似值而非精确值传入工具则会直接抛出ValueError而不是静默返回一个漏掉工具 schema 的计数仅统计普通消息无系统指令、无工具时两个后端都可用。因此如果你的 Agent 需要精确统计系统提示词或工具 schema 的 token请使用apivertex。该注意事项在 GoogleGenAITokenCounter 组件文档 中亦有对应描述。生命周期warm_up()创建客户端在应用启动阶段预创建可避免首次调用的延迟close()关闭客户端并释放底层 HTTP 资源to_dict/from_dict支持序列化与反序列化。八、实战组合一条完整的 RAG 检索管线把上述组件组装成可运行的 RAG 场景示例出自 googlegenaidocumentembedder 组件指南与 googlegenaitextembedder 组件指南from haystack import Document from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.writers import DocumentWriter from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack_integrations.components.embedders.google_genai import ( GoogleGenAITextEmbedder, GoogleGenAIDocumentEmbedder, ) document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] indexing_pipeline Pipeline() indexing_pipeline.add_component(embedder, GoogleGenAIDocumentEmbedder()) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run({embedder: {documents: documents}}) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, GoogleGenAITextEmbedder()) query_pipeline.add_component( retriever, InMemoryEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query Who lives in Berlin? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0]) ## Document(id..., content: My name is Wolfgang and I live in Berlin)该示例中的关键配合点索引侧GoogleGenAIDocumentEmbedder产出带嵌入的文档 →DocumentWriter写入InMemoryDocumentStoredocument_store.py查询侧GoogleGenAITextEmbedder把查询编码为向量 →InMemoryEmbeddingRetrieverembedding_retriever.py用余弦相似度召回最相关文档两侧必须使用同一模型才能保证文档向量与查询向量处于同一向量空间。多模态场景同理索引时用GoogleGenAIMultimodalDocumentEmbedder嵌入图片/PDF/视频/音频文件查询时仍用GoogleGenAITextEmbedder编码文本查询即可实现文本查图、文本查视频的跨模态检索。九、序列化与生命周期管理参考文档中所有组件都实现了统一的生命周期与序列化接口便于在 Haystack 的 YAML/JSON 管线声明中使用方法行为warm_up()创建同步 Google Gen AI 客户端warm_up_async()创建异步 Google Gen AI 客户端close()关闭同步客户端close_async()关闭异步客户端to_dict() - dict[str, Any]序列化为字典from_dict(data) - 组件实例从字典反序列化run(...)/run_async(...)同步 / 异步执行其中to_dict/from_dict是 Haystack 组件可被Pipeline.dump/Pipeline.load持久化、可写入 YAML 管线的基石而warm_up/close对应组件的资源生命周期管理如释放 HTTP 连接池在长运行服务与异步应用中尤其重要。各组件的run_async与run参数、返回值和异常语义保持一致只是可被await。结语至此google-genai-haystack集成的完整能力已全部覆盖文本嵌入GoogleGenAIDocumentEmbedder、多模态嵌入GoogleGenAIMultimodalDocumentEmbedder含root_path路径安全与image_size缩放、查询编码GoogleGenAITextEmbedder、带思考预算/思考深度/工具/结构化输出/多模态输入的GoogleGenAIChatGenerator以及基于官方countTokens的GoogleGenAITokenCounter注意其系统指令与工具统计的 Vertex AI 边界。配合 Haystack 的Pipeline、InMemoryDocumentStore与InMemoryEmbeddingRetriever即可快速构建生产级的 RAG 与 Agent 应用。进一步细节可查阅仓库中的 Google GenAI 参考文档 及对应的 Embedder 组件指南、ChatGenerator 组件指南。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Haystack 集成 Google GenAI从 Gemini 文本/多模态嵌入到带思考能力的 ChatGenerator 与 Token 计数完整实战指南【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本篇技术指南以 Haystack Google GenAI 集成参考文档 为核心骨架系统讲解google-genai-haystack集成在 Haystack 中的全部组件三类 Embedder文本文档、多模态文档、查询文本、支持思考能力与工具调用的GoogleGenAIChatGenerator以及基于countTokens接口的GoogleGenAITokenCounter。读完本文你将掌握从三种认证方式的选择、嵌入参数调优、多模态文件嵌入的路径安全配置到组装完整 RAG/Agent 管线的全部实战细节。一、集成概览一套包五类能力google-genai-haystack是基于 Google 官方 Gen AI SDKpython-genai构建的 Haystack 集成包兼容 Gemini Developer API 与 Vertex AI 两套后端。参考文档将其能力划分为五个模块全部以haystack_integrations命名空间暴露模块类职责components.embedders.google_genai.document_embedderGoogleGenAIDocumentEmbedder用 Google AI 模型计算文本文档的嵌入向量components.embedders.google_genai.multimodal_document_embedderGoogleGenAIMultimodalDocumentEmbedder计算非文本文档图片、PDF、视频、音频的嵌入映射到同一向量空间components.embedders.google_genai.text_embedderGoogleGenAITextEmbedder将字符串如用户查询编码为向量供嵌入检索器使用components.generators.google_genai.chat.chat_generatorGoogleGenAIChatGenerator基于 Gemini 模型的聊天补全支持思考thinking、工具、结构化输出与多模态输入token_counters.google_genai.token_counterGoogleGenAITokenCounter调用 Google 官方countTokens接口精确统计 Gemini 输入 token安装方式统一为pip install google-genai-haystack从组件关系上看三类 Embedder 负责把文档与查询映射到同一向量空间这是向量检索成立的前提ChatGenerator 负责生成环节TokenCounter 则服务于 Agent 上下文管理与成本预估。配套的分组件使用指南可在 embedders 文档目录 与 generators 文档目录 中找到。二、认证方式三套配置覆盖两种后端参考文档中所有组件都共享同一套认证设计api_key参数默认从GOOGLE_API_KEY或GEMINI_API_KEY环境变量读取strictFalse两个变量都未设置时才报错并通过api参数在geminiGemini Developer API与vertexVertex AI之间切换。三种写法如下以 DocumentEmbedder 为例其余组件完全同构1. Gemini Developer APIAPI Key 认证from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) document_embedder GoogleGenAIDocumentEmbedder(modelgemini-embedding-001)2. Vertex AIApplication Default Credentialsfrom haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # Using Application Default Credentials (requires gcloud auth setup) document_embedder GoogleGenAIDocumentEmbedder( apivertex, vertex_ai_projectmy-project, vertex_ai_locationus-central1, modelgemini-embedding-001 )3. Vertex AIAPI Key 认证from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder # export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) document_embedder GoogleGenAIDocumentEmbedder( apivertex, modelgemini-embedding-001 )认证机制与 Secret 管理这套设计背后的核心抽象是 Haystack 的Secret类实现见 haystack/utils/auth.pySecret.from_env_var([GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse)按顺序解析第一个已设置的环境变量strictFalse表示变量缺失时不抛异常留给运行期报错。Secret.from_token(your-api-key)直接把密钥写进初始化参数文档明确标注 token 型 Secret 不可序列化源码说明适合交互式脚本生产环境仍推荐环境变量方式。Vertex AI 的 ADCApplication Default Credentials模式不需要 API Key但必须显式传入vertex_ai_project与vertex_ai_location如us-central1、europe-west1并提前完成 gcloud 认证配置。三、GoogleGenAIDocumentEmbedder文本文档批量向量化该组件使用 Google AI 模型计算文档嵌入输出会被写入每个Document的embedding字段——这正是 Document 数据类 中embedding: list[float]字段的用途。它通常位于索引管线的DocumentWriter之前。完整初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-embedding-001, prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None参数详解参数类型默认值说明api_keySecret环境变量GOOGLE_API_KEY/GEMINI_API_KEYVertex AI 配合 ADC 时无需提供apiLiteral[gemini, vertex]gemini选择 Gemini Developer API 或 Vertex AIvertex_ai_projectstr \| NoneNoneVertex AI ADC 模式必需GCP 项目 IDvertex_ai_locationstr \| NoneNoneVertex AI ADC 模式必需如us-central1modelstrgemini-embedding-001嵌入模型名prefixstr文本前附加字符串可用于为gemini-embedding-2指定任务类型task typesuffixstr文本末尾附加字符串batch_sizeint32单次批量嵌入的文档数progress_barboolTrue运行是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要随正文一起嵌入的元数据字段列表embedding_separatorstr\n拼接元数据与正文时使用的分隔符configdict[str, Any] \| NoneNone透传给 Google SDKEmbedContentConfig的参数字典注意在config中指定 task type 对gemini-embedding-2不生效timeoutfloat \| NoneNone底层 Google GenAI 客户端网络请求超时秒max_retriesint \| NoneNone底层客户端最大重试次数使用示例from haystack import Document from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder doc Document(contentI love pizza!) document_embedder GoogleGenAIDocumentEmbedder() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run(documents)返回字典含两个键documents已携带嵌入向量的文档列表与meta模型用量信息如 token 数。进阶把语义化元数据一并嵌入文档自带元数据如果语义鲜明可以一并编码以提升检索质量参考 GoogleGenAIDocumentEmbedder 组件指南from haystack import Document from haystack.utils import Secret from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder doc Document(contentsome text, meta{title: relevant title, page number: 18}) embedder GoogleGenAIDocumentEmbedder( api_keySecret.from_token(your-api-key), meta_fields_to_embed[title], ) docs_w_embeddings embedder.run(documents[doc])[documents]拼接规则为content embedding_separator meta 字段值默认分隔符是换行符\n可通过embedding_separator调整。四、GoogleGenAITextEmbedder查询字符串向量化与 DocumentEmbedder 对应GoogleGenAITextEmbedder使用 Google AI 模型嵌入字符串典型场景是查询侧把用户问题编码后交给嵌入检索器Embedding Retriever做相似度检索。初始化签名与差异点__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-embedding-001, prefix: str , suffix: str , config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None它没有batch_size/progress_bar/meta_fields_to_embed等批处理参数因为每次只嵌一个字符串其余参数语义与 DocumentEmbedder 完全一致。使用示例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: gemini-embedding-001-v2, # usage: {prompt_tokens: 4, total_tokens: 4}}}run(text)返回embedding输入文本的向量与meta模型名与 token 用量。注意meta中的模型名会带上服务端实际使用的版本后缀如gemini-embedding-001-v2可作为确认所用模型版本的依据。五、GoogleGenAIMultimodalDocumentEmbedder图片/PDF/视频/音频统一嵌入该组件是文档中唯一面向非文本内容的嵌入器支持图片、PDF、视频与音频文件并把它们映射到同一个向量空间从而可以与文本嵌入直接做相似度比较。文本文档请用GoogleGenAIDocumentEmbedder查询字符串请用GoogleGenAITextEmbedder。初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, file_path_meta_field: str file_path, root_path: str | None None, image_size: tuple[int, int] | None None, model: str gemini-embedding-2, batch_size: int 6, progress_bar: bool True, config: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None ) - None参数详解参数类型默认值说明file_path_meta_fieldstrfile_pathDocument 元数据中存放待嵌入文件路径的字段名root_pathstr \| NoneNone文件根目录设置后元数据中的路径将相对该目录解析并保证不越出该目录为None时路径按绝对路径处理且不做越界检查。若元数据可能受不可信输入影响务必设置专用数据目录以拒绝路径穿越image_sizetuple[int, int] \| NoneNone仅作用于图片与 PDF 页等比缩放至指定宽, 高范围内降低文件体积、内存占用与传输耗时适合有分辨率限制的模型modelstrgemini-embedding-2嵌入模型名参考文档示例亦用gemini-embedding-2-previewbatch_sizeint6单批嵌入文档数最大批大小随输入类型变化configdict[str, Any] \| NoneNone嵌入内容配置例如设置输出维度{output_dimensionality: 768}其余api_key/api/vertex_ai_project/vertex_ai_location/progress_bar/timeout/max_retries语义与前两类组件相同。使用示例from haystack import Document from haystack_integrations.components.embedders.google_genai import GoogleGenAIMultimodalDocumentEmbedder doc Document(contentNone, meta{file_path: path/to/image.jpg}) document_embedder GoogleGenAIMultimodalDocumentEmbedder() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]注意Document的content为None文件路径放在meta[file_path]可通过file_path_meta_field改名。这与 Document 数据类 中content可为 None、meta承载扩展信息的设计一致。异常语义值得注意的健壮性设计参考文档为run与run_async明确列出了三类异常便于调用方捕获处理TypeError输入不是Document列表ValueError文档缺失文件路径元数据字段、文件路径越出root_path、或 MIME 类型不受支持RuntimeError部分文档转换失败。其中root_path的路径越界校验是安全相关的关键设计——当文档元数据可能来自不可信来源如外部导入的文档集时设置root_path可有效防止路径遍历攻击。六、GoogleGenAIChatGeneratorGemini 对话生成与思考能力GoogleGenAIChatGenerator通过 Google Gen AI SDK 完成 Gemini 对话补全是集成中功能最丰富的组件支持思考thinking、工具调用、结构化输出、流式与多模态输入。支持的模型SUPPORTED_MODELS: list[str] [ gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-3.1-flash-lite-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, ]该列表是非穷尽的参考文档原文即注明 A non-exhaustive list更完整的模型 ID 以 Google 官方模型文档为准。思考能力Thinking Support针对 Gemini 2.5 与 Gemini 3 系列模型组件开放了思考配置推理透明化模型可以展示推理过程思维签名Thought Signatures多轮对话配合工具时通过加密的保存状态维持跨轮次的思维上下文——因此使用工具时应把之前的助手回复保留在聊天历史中可配置思考预算精确控制分配给推理的 token。通过generation_kwargs{thinking_budget: value}配置thinking_budget含义-1动态分配默认0禁用思考仅 Flash / Flash-Lite 系列正整数N显式设置 token 预算Gemini 3 系列及更新模型还支持thinking_level思考深度可选minimal接近无思考仅复杂编码任务会有极少量思考延迟最低、low适合简单指令遵循、对话与高吞吐场景、medium多数任务的均衡档、high默认动态档推理最深但首 token 延迟显著增大。初始化签名__init__( *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, model: str gemini-3.7-flash, generation_kwargs: dict[str, Any] | None None, safety_settings: list[dict[str, Any]] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, timeout: float | None None, max_retries: int | None None ) - None关键参数generation_kwargs承载 temperature、max_tokens 以及上文的thinking_budget/thinking_levelsafety_settings控制内容过滤streaming_callback在收到新 token 时被调用tools接受Tool和/或Toolset的列表或单个Toolset每个工具名须唯一timeout/max_retries未设置时采用 Google Gen AI 客户端默认值。使用示例开启思考并读取推理内容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( modelgemini-3.7-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(messagesmessages) 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)replies中每条ChatMessage的reasonings字段承载推理内容——该字段在 Haystack 中由 ReasoningContent 内容类型 表示其中reasoning_text即推理文本。使用示例带思考的工具调用# Tool usage example with thinking def weather_function(city: str): return fThe weather in {city} is sunny and 25°C weather_tool Tool( nameweather, descriptionGet weather information for a city, parameters{type: object, properties: {city: {type: string}}, required: [city]}, functionweather_function ) # Can use either List[Tool] or Toolset chat_generator_with_tools GoogleGenAIChatGenerator( modelgemini-3.7-flash, tools[weather_tool], # or toolsToolset([weather_tool]) generation_kwargs{thinking_budget: -1} # Dynamic thinking allocation ) messages [ChatMessage.from_user(Whats the weather in Paris?)] response chat_generator_with_tools.run(messagesmessages)组件指南googlegenaichatgenerator.mdx进一步说明tools参数支持混用单个工具列表、单个 Toolset、以及多个 Toolset 独立工具的混合列表便于把相关工具逻辑分组。工具调用后的结果回合通常由 Haystack 的ToolInvoker执行见 haystack/components/tools 目录。使用示例结构化输出from pydantic import BaseModel from haystack.dataclasses.chat_message import ChatMessage from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator class City(BaseModel): name: str country: str population: int chat_generator GoogleGenAIChatGenerator( modelgemini-3.7-flash, generation_kwargs{response_format: City} ) messages [ChatMessage.from_user(Tell me about Paris)] response chat_generator.run(messagesmessages) print(response[replies][0].text) # JSON output matching the City schema通过generation_kwargs{response_format: Pydantic 模型}直接约束输出为符合 schema 的 JSON。使用示例ChatMessage 内嵌 FileContent 多模态输入from haystack.dataclasses import ChatMessage, FileContent from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator file_content FileContent.from_url(https://arxiv.org/pdf/2309.08632) chat_message ChatMessage.from_user(content_parts[file_content, Summarize this paper in 100 words.]) chat_generator GoogleGenAIChatGenerator() response chat_generator.run(messages[chat_message])FileContent是 haystack/dataclasses/file_content.py 中定义的内容类型承载 base64 数据与 MIME 类型from_url通过内置的LinkContentFetcher下载文件并自动推断 MIME 类型实现见 file_content.py。图片场景还可使用ImageContent.from_file_pathimage_content.py它支持缩放与格式校验。run 方法签名与覆盖规则run( messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, safety_settings: list[dict[str, Any]] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, ) - dict[str, Any]要点messages也接受裸字符串会自动包装成一条 user 角色的ChatMessagegeneration_kwargs按key 粒度与初始化时的配置合并run 传入的 key 优先仅初始化设置的 key 保留safety_settings、tools传入后会覆盖初始化时设置的对应值返回值仅含replies生成的ChatMessage列表异常RuntimeError生成过程出错ValueError某条ChatMessage不包含TextContent/ToolCall/ToolCallResult中的任何一种或角色不是 User/System/Assistant。角色体系定义见 chat_message.py 中的 ChatRole。run_async为完全对应的异步版本支持await。七、GoogleGenAITokenCounter官方接口的精确 Token 计数GoogleGenAITokenCounter调用 Google Gen AI SDK 的countTokens端点统计 Gemini 输入 token。与本地估算类计数器不同它把消息原样发送到官方端点因此计数包含 Gemini 对消息施加的模型专属格式化formatting。输入按GoogleGenAIChatGenerator的发送方式装配首条 system 消息作为系统指令其余消息作为请求内容。初始化签名__init__( model: str, *, api_key: Secret Secret.from_env_var( [GOOGLE_API_KEY, GEMINI_API_KEY], strictFalse ), api: Literal[gemini, vertex] gemini, vertex_ai_project: str | None None, vertex_ai_location: str | None None, timeout: float | None None, max_retries: int | None None ) - Nonemodel是必填位置参数token 计数与模型相关应传入你实际用于生成的同一模型。使用示例from haystack.dataclasses import ChatMessage from haystack_integrations.token_counters.google_genai import GoogleGenAITokenCounter counter GoogleGenAITokenCounter(gemini-3.7-flash) messages [ChatMessage.from_user(Hello, how are you?)] token_count counter.count(messages) print(fToken count: {token_count})count(messages, toolsNone)返回int无可测内容时返回0传入tools时其 schema 也会计入 token。后端差异系统指令与工具的支持边界这是参考文档明确强调的重要坑点Google Gen AI SDK 只有在客户端指向Vertex AI时才接受在countTokens上传系统指令与工具 schema在Gemini Developer API上首条 system 消息会被当作 user 轮次统计是近似值而非精确值传入工具则会直接抛出ValueError而不是静默返回一个漏掉工具 schema 的计数仅统计普通消息无系统指令、无工具时两个后端都可用。因此如果你的 Agent 需要精确统计系统提示词或工具 schema 的 token请使用apivertex。该注意事项在 GoogleGenAITokenCounter 组件文档 中亦有对应描述。生命周期warm_up()创建客户端在应用启动阶段预创建可避免首次调用的延迟close()关闭客户端并释放底层 HTTP 资源to_dict/from_dict支持序列化与反序列化。八、实战组合一条完整的 RAG 检索管线把上述组件组装成可运行的 RAG 场景示例出自 googlegenaidocumentembedder 组件指南与 googlegenaitextembedder 组件指南from haystack import Document from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.writers import DocumentWriter from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack_integrations.components.embedders.google_genai import ( GoogleGenAITextEmbedder, GoogleGenAIDocumentEmbedder, ) document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] indexing_pipeline Pipeline() indexing_pipeline.add_component(embedder, GoogleGenAIDocumentEmbedder()) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run({embedder: {documents: documents}}) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, GoogleGenAITextEmbedder()) query_pipeline.add_component( retriever, InMemoryEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query Who lives in Berlin? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0]) ## Document(id..., content: My name is Wolfgang and I live in Berlin)该示例中的关键配合点索引侧GoogleGenAIDocumentEmbedder产出带嵌入的文档 →DocumentWriter写入InMemoryDocumentStoredocument_store.py查询侧GoogleGenAITextEmbedder把查询编码为向量 →InMemoryEmbeddingRetrieverembedding_retriever.py用余弦相似度召回最相关文档两侧必须使用同一模型才能保证文档向量与查询向量处于同一向量空间。多模态场景同理索引时用GoogleGenAIMultimodalDocumentEmbedder嵌入图片/PDF/视频/音频文件查询时仍用GoogleGenAITextEmbedder编码文本查询即可实现文本查图、文本查视频的跨模态检索。九、序列化与生命周期管理参考文档中所有组件都实现了统一的生命周期与序列化接口便于在 Haystack 的 YAML/JSON 管线声明中使用方法行为warm_up()创建同步 Google Gen AI 客户端warm_up_async()创建异步 Google Gen AI 客户端close()关闭同步客户端close_async()关闭异步客户端to_dict() - dict[str, Any]序列化为字典from_dict(data) - 组件实例从字典反序列化run(...)/run_async(...)同步 / 异步执行其中to_dict/from_dict是 Haystack 组件可被Pipeline.dump/Pipeline.load持久化、可写入 YAML 管线的基石而warm_up/close对应组件的资源生命周期管理如释放 HTTP 连接池在长运行服务与异步应用中尤其重要。各组件的run_async与run参数、返回值和异常语义保持一致只是可被await。结语至此google-genai-haystack集成的完整能力已全部覆盖文本嵌入GoogleGenAIDocumentEmbedder、多模态嵌入GoogleGenAIMultimodalDocumentEmbedder含root_path路径安全与image_size缩放、查询编码GoogleGenAITextEmbedder、带思考预算/思考深度/工具/结构化输出/多模态输入的GoogleGenAIChatGenerator以及基于官方countTokens的GoogleGenAITokenCounter注意其系统指令与工具统计的 Vertex AI 边界。配合 Haystack 的Pipeline、InMemoryDocumentStore与InMemoryEmbeddingRetriever即可快速构建生产级的 RAG 与 Agent 应用。进一步细节可查阅仓库中的 Google GenAI 参考文档 及对应的 Embedder 组件指南、ChatGenerator 组件指南。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
