Haystack 集成指南：使用 LiteLLMChatGenerator 统一接入 100+ LLM 提供商的对话生成

Haystack 集成指南使用 LiteLLMChatGenerator 统一接入 100 LLM 提供商的对话生成【免费下载链接】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 官方集成litellm-haystack中的LiteLLMChatGenerator组件为核心系统讲解如何通过 LiteLLM 的统一接口在 Haystack 中调用 OpenAI、Anthropic、AWS Bedrock、Azure、Cohere、Mistral、Groq 等 100 提供商的对话模型。读完本文你将掌握该组件的完整初始化参数、run/run_async运行时调用、凭证管理、函数调用Tool Calling、流式输出、序列化以及如何将它接入Pipeline构建可切换模型供应商的 RAG/Agent 应用。一、组件概览一个接口切换任意模型供应商LiteLLMChatGenerator是 Haystack 生态中的 Chat Generator 组件核心定位是通过 LiteLLM 这一开源代理层把大量 LLM 提供商的对话补全chat completion能力统一收敛到一个接口之下。它路由到的提供商包括 OpenAI、Anthropic、Google、AWS Bedrock、Azure、Cohere、Mistral、Groq 等模型切换只需修改model字符串无需重写 Pipeline 中的任何逻辑。在 Pipeline 中它通常位于ChatPromptBuilder之后见用户指南 litellmchatgenerator.mdx 的Most common position in a pipeline说明输入为ChatMessage列表输出为键replies对应的ChatMessage列表。该组件来自独立的litellm-haystack包与核心 Haystack 分离维护安装方式pip install litellm-haystack本组件完整 API 签名见版本参考文档 version-2.22/integrations-api/litellm.md最新版见 reference/integrations-api/litellm.md。二、快速上手最小可运行示例API 参考文档给出的最小示例可以直接运行from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator from haystack.dataclasses import ChatMessage generator LiteLLMChatGenerator( modelanthropic/claude-sonnet-4-20250514, generation_kwargs{max_tokens: 1024, temperature: 0.7}, ) messages [ ChatMessage.from_system(You are a helpful assistant), ChatMessage.from_user(Whats Natural Language Processing?), ] result generator.run(messagesmessages) print(result[replies][0].text)关键点拆解messages由ChatMessage构成。在 Haystack 中ChatMessage是承载对话消息的核心数据类源码见 chat_message.py内部使用ChatRole枚举区分user、system、assistant、tool四种角色并提供from_user、from_system、from_assistant、from_tool等工厂方法构造消息。run结果通过result[replies]取回模型生成的助手回复replies[0].text即回复文本ChatMessage.text属性返回消息中第一条文本内容见源码 chat_message.py。组件默认模型为openai/gpt-4o。若未显式传入api_keyLiteLLM 会自行从提供商的标准环境变量如ANTHROPIC_API_KEY、OPENAI_API_KEY解析凭证。三、初始化参数详解__init__LiteLLMChatGenerator的构造签名全部为关键字参数__init__( *, api_key: Secret | None None, model: str openai/gpt-4o, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None None, generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None ) - None各参数说明与实战建议参数类型默认值说明与实战建议api_keySecret \| NoneNone提供商 API 密钥。留空时LiteLLM 自动从提供商标准环境变量如ANTHROPIC_API_KEY、OPENAI_API_KEY解析凭证这是推荐做法传入Secret时则交由 Haystack 显式管理与序列化密钥例如Secret.from_env_var(OPENAI_API_KEY)。modelstropenai/gpt-4oLiteLLM 格式的模型名形如provider/model-name见下文模型命名。streaming_callbackStreamingCallbackT \| NoneNone流式回调函数每次收到新的StreamingChunk时被调用可传入内置的print_streaming_chunk或自定义回调。api_base_urlstr \| NoneNone自定义 API Base URL用于对接自托管的 LiteLLM 代理LiteLLM Proxy Server或其他兼容端点。generation_kwargsdict[str, Any] \| NoneNone透传给底层litellm.completion()的额外生成参数如max_tokens、temperature、top_p等。LiteLLM 会跨提供商做参数归一化并在目标提供商不支持某参数时将其丢弃。toolsToolsType \| NoneNone可供模型准备调用的工具Tool或工具集Toolset列表用于函数调用见工具调用小节。关于SecretHaystack 的密钥抽象定义在 auth.pySecret.from_env_var(OPENAI_API_KEY)会惰性地从指定环境变量读取值仅在调用resolve_value()时才解析从而避免在组件初始化时强制暴露明文密钥。当组件被序列化为 YAML/JSON 时密钥以环境变量引用形式保存而非明文。四、模型命名格式与凭证管理4.1provider/model-name命名约定模型名必须使用 LiteLLM 的provider/model-name格式即提供商前缀 斜杠 模型标识。API 参考文档给出的示例anthropic/claude-sonnet-4-20250514—— Anthropic Claudeopenai/gpt-4o—— OpenAI也是组件默认模型bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0—— AWS Bedrock 托管的 Claude提供商前缀决定了 LiteLLM 采用哪套 SDK 与鉴权方式路由请求。完整提供商与模型标识列表可查阅 LiteLLM 官方的 providers 文档docs.litellm.ai/docs/providers。4.2 凭证提供的两种方式组件文档明确给出了两种 API Key 提供方式推荐交给 LiteLLM 解析环境变量。保持api_keyNoneLiteLLM 按提供商约定从标准环境变量读取例如OPENAI_API_KEY、ANTHROPIC_API_KEY。这种方式下 Haystack 不接触密钥。显式传入SecretLiteLLMChatGenerator(api_keySecret.from_env_var(OPENAI_API_KEY), ...)。仅在希望 Haystack 统一管理并序列化密钥时使用。4.3 自定义端点与自托管代理若你运行的是自托管的 LiteLLM 代理LiteLLM Proxy或自定义兼容端点通过api_base_url指定其地址即可例如generator LiteLLMChatGenerator( modelopenai/gpt-4o, api_base_urlhttp://localhost:4000, # 自托管 LiteLLM Proxy 地址 )五、运行时调用run与run_async5.1runrun( messages: list[ChatMessage] | str, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None ) - dict[str, list[ChatMessage]]参数说明messages输入消息。可以是ChatMessage实例列表若直接传str组件内部会将其转换为仅含一个user角色ChatMessage的列表方便快速调用。streaming_callback仅对本次调用生效的回调覆盖不传则使用初始化时的回调。generation_kwargs仅对本次调用生效的生成参数覆盖与初始化参数合并/覆盖。tools仅对本次调用生效的工具覆盖。返回值字典键为replies值为ChatMessage列表。5.2run_asyncrun_async是run的异步版本签名与参数语义完全一致用于异步 Pipeline 与异步应用如 FastAPI 服务run_async( messages: list[ChatMessage] | str, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None ) - dict[str, list[ChatMessage]]注意异步模式下若启用流式需要传入异步流式回调async streaming callback。5.3 序列化to_dict/from_dictto_dict() - dict[str, Any]将组件序列化为字典含模型名、生成参数、工具、密钥引用等配置可再经 YAML 等格式落盘或传输。from_dict(data: dict[str, Any]) - LiteLLMChatGenerator从字典反序列化还原组件实例。这一对方法使LiteLLMChatGenerator满足 Haystack 组件序列化协议可被Pipeline.dumps()/Pipeline.loads()与 YAML 定义文件见仓库 marshal/yaml.py直接使用。六、函数调用Tool CallingLiteLLMChatGenerator通过tools参数支持函数调用且工具配置非常灵活见用户指南 litellmchatgenerator.mdxTool 列表传入一组独立的Tool对象单个 Toolset直接传入一个完整的Toolset混合形态在同一列表中混用多个Toolset与独立Tool。工具调用在同步与流式响应下均可工作前提是底层提供商与模型支持 function calling。在流式场景中工具调用的增量参数会随StreamingChunk携带见下文流式输出Haystack 内置的print_streaming_chunk会实时打印[TOOL CALL]、[TOOL RESULT]标记。关于 Tool/Toolset 的完整用法可参考 tool.mdx 与 toolset.mdx。七、流式输出Streaming通过streaming_callback参数初始化或run时传入即可开启流式输出回调会在每个StreamingChunk到达时被触发。最简单的方式是使用内置回调print_streaming_chunk它会把文本 token、工具调用与工具结果实时打印到标准输出源码实现见 generators/utils.pyfrom haystack.components.generators.utils import print_streaming_chunk from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator generator LiteLLMChatGenerator( modelopenai/gpt-4o, streaming_callbackprint_streaming_chunk, ) generator.run([ChatMessage.from_user(Your question here)])从源码看StreamingChunk数据结构streaming_chunk.py包含以下关键字段自定义回调时可充分利用content流式到达的文本片段增量 tokenstart是否为某个内容块的开头index内容块序号用于区分多个内容块tool_callsToolCallDelta列表承载流式工具调用函数名与增量参数tool_call_resultToolCallResult完整的工具调用结果finish_reason结束原因遵循 OpenAI 惯例stop、length、tool_calls、content_filter等reasoningReasoningContent模型的推理内容meta附加元数据。print_streaming_chunk的处理逻辑展示了这些字段的协作方式遇到chunk.start时打印[ASSISTANT]标记存在tool_calls时打印[TOOL CALL]与函数名、参数增量存在tool_call_result时打印[TOOL RESULT]及结果文本存在reasoning时打印[REASONING]推理内容。自定义回调只需接收一个StreamingChunk参数即可例如把增量文本累积到列表中以实现逐 token 的 UI 展示。八、在 Pipeline 中组合使用LiteLLMChatGenerator与ChatPromptBuilder搭配是典型用法——由ChatPromptBuilder渲染带模板变量的系统提示与用户消息再将消息列表喂给生成器。官方文档示例from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.litellm import LiteLLMChatGenerator pipe Pipeline() pipe.add_component(prompt_builder, ChatPromptBuilder()) pipe.add_component(llm, LiteLLMChatGenerator(modelopenai/gpt-4o)) pipe.connect(prompt_builder, llm) country Germany system_message ChatMessage.from_system( You are an assistant giving out valuable information to language learners., ) messages [ system_message, ChatMessage.from_user(Whats the official language of {{ country }}?), ] res pipe.run( data{ prompt_builder: { template_variables: {country: country}, template: messages, }, }, ) print(res)由于LiteLLMChatGenerator遵守标准的组件输入输出协议输入messages、输出replies替换模型供应商时只需改model参数Pipeline 拓扑与上下游连接完全不动——这正是 LiteLLM 统一接口在 Haystack 中的核心价值。若你的 Pipeline 中还需要缓存、检索等环节可参考仓库内ChatMessage相关文档 chatmessage.mdx 与ChatPromptBuilder文档 chatpromptbuilder.mdx。九、最佳实践与注意事项优先使用环境变量凭证除非确有密钥托管与序列化需求否则保持api_keyNone让 LiteLLM 从提供商标准环境变量解析避免密钥随配置落盘。generation_kwargs的归一化行为litellm.completion()会跨提供商统一参数语义例如各家的max_tokens并在目标提供商不支持时丢弃多余参数。这意味着你可以为 Anthropic 写{max_tokens: 1024}、为 OpenAI 写同一份参数而无需调整。工具调用依赖模型能力tools是否生效取决于底层模型是否支持 function calling流式场景下工具增量参数通过StreamingChunk.tool_calls下发回调需正确处理增量累积。异步场景配对异步回调使用run_async且开启流式时应传入异步流式回调。序列化安全to_dict/from_dict使组件可在 YAML/JSON 中定义与还原密钥以Secret引用形式序列化反序列化来自不可信来源的配置时应遵循 Haystack 的安全反序列化规范。十、相关资源组件 API 参考本文依据version-2.22/integrations-api/litellm.md 与最新版 reference/integrations-api/litellm.md用户指南litellmchatgenerator.mdx相关源码StreamingChunk 定义、print_streaming_chunk 实现、ChatMessage 数据类、Secret 工具类关联文档ChatMessage 概念、Secret 管理、Tool、Toolset、ChatPromptBuilder【免费下载链接】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），仅供参考