Haystack 与 LiteLLM 集成实战用 LiteLLMChatGenerator 统一调用 100 大模型提供商【免费下载链接】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/haystackLiteLLM 集成是 Haystack 生态中负责模型网关的一环LiteLLMChatGenerator通过 LiteLLM 的统一接口把 OpenAI、Anthropic、Google、AWS Bedrock、Azure、Cohere、Mistral、Groq 等 100 提供商的对话补全能力接入 Haystack 流水线。读完本文你将掌握该组件的完整初始化参数、run/run_async调用方式、函数调用Tools与流式输出Streaming的用法以及如何把它与ChatPromptBuilder组合成一条可运行的 RAG 对话流水线。一、组件定位为什么需要 LiteLLM 集成在 Haystack 中generators 目录 下按具体厂商提供了 OpenAI、Anthropic、Cohere、HuggingFace 等专属 Chat Generator。每个组件都封装了对应厂商的 API 细节。而LiteLLMChatGenerator走的是另一条路线它把请求统一转发给 LiteLLM由 LiteLLM 负责各厂商协议与鉴权差异的归一化。它的直接收益是换模型不换代码切换提供商时只需修改model字符串以及对应的环境变量流水线结构完全不变。模型名统一使用 LiteLLM 的provider/model-name格式例如openai/gpt-4oanthropic/claude-sonnet-4-20250514bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0组件默认模型为openai/gpt-4o。完整的提供商与模型标识列表以 LiteLLM 官方 providers 文档为准。从参考文档的模块路径haystack_integrations.components.generators.litellm.chat.chat_generator可以看出该组件是litellm-haystack集成包的一部分与核心仓库解耦发布。二、安装与基本使用该组件独立打包发布安装命令为pip install litellm-haystack装好后即可独立使用脱离流水线直接调用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)这里用到的ChatMessage是 Haystack 的核心对话数据类在 chat_message.py 中定义内部包含role说话方角色、content消息内容可为文本、ToolCall、ToolCallResult 等、可选的name与meta。创建消息推荐使用类方法from_system、from_user、from_assistant、from_tool见 chat_message.py而不是手动构造。运行结果是一个字典键为replies值为ChatMessage列表通过result[replies][0].text即可取到模型回复文本。三、初始化参数详解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 \| None目标提供商的 API Key可选。不传时 LiteLLM 会自行从提供商的标准环境变量解析凭证如OPENAI_API_KEY、ANTHROPIC_API_KEY这是推荐做法。只有当你想让 Haystack 显式管理和序列化该密钥时才传入Secret。modelstrLiteLLM 格式的模型名provider/model-name默认openai/gpt-4o。streaming_callbackStreamingCallbackT \| None流式回调函数每个新的StreamingChunk到达时被调用。api_base_urlstr \| None自定义 API Base URL适用于自托管的 LiteLLM Proxy 或自定义端点。generation_kwargsdict[str, Any] \| None透传给litellm.completion()的附加生成参数。LiteLLM 会跨提供商归一化这些参数并丢弃目标提供商不支持的项。toolsToolsType \| None供模型准备调用的 Tool / Toolset 对象列表。3.1 凭证的两种注入方式推荐——环境变量什么都不用传LiteLLM 自动从OPENAI_API_KEY、ANTHROPIC_API_KEY等标准环境变量读取凭证。显式传入通过 Haystack 的SecretAPI 包装密钥例如Secret.from_env_var(OPENAI_API_KEY)。只有当需要 Haystack 管理并序列化密钥时才使用。Secret定义在 auth.py支持from_token令牌形式不可序列化和from_env_var环境变量形式支持传入多个候选环境变量并按序解析两种静态工厂方法。3.2 生成参数透传generation_kwargs几乎可以放任何litellm.completion()支持的参数例如max_tokens、temperature、top_p、stop等。它既可以放在__init__中作为默认值也可以在run/run_async时按单次调用覆盖。由于 LiteLLM 负责参数归一化同一份generation_kwargs在不同厂商模型间迁移时能保持语义一致。四、run 与 run_async同步与异步调用4.1 runrun( 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输入消息列表。也可直接传入str组件会将其转换为一条user角色的ChatMessage参考文档明确说明此行为。streaming_callback覆盖本次调用的流式回调。generation_kwargs覆盖本次调用的生成参数。tools覆盖本次调用的工具列表仅限关键字参数。返回值为dict[str, list[ChatMessage]]键为replies值为ChatMessage列表。4.2 run_asyncrun_async是run的异步版本签名与run完全一致返回同样的dict[str, list[ChatMessage]]。它面向异步流水线Pipeline.run_async与异步应用支持普通与流式两种响应模式——使用流式时需传入异步流式回调。该组件也因此可以平滑接入 Haystack 的异步执行体系。五、函数调用Tools支持LiteLLMChatGenerator通过tools参数支持函数调用且接受灵活的配置形式Tool 列表把单个 Tool 以列表形式传入单个 Toolset直接传入整个 Toolset混合形式在同一个列表中混用多个 Toolset 与独立 Tool。工具调用在同步与流式响应下都可用前提是底层提供商与模型支持函数调用。ToolsType类型定义了这些可接受的形态。ChatMessage内部通过tool_calls、tool_call_results属性暴露模型生成的工具调用及执行结果见 chat_message.py因此工具调用可以无缝编入多轮对话历史。六、流式输出Streaming流式输出通过streaming_callback参数开启。Haystack 内置了一个开箱即用的回调print_streaming_chunk位于 utils.py它会把流式到达的文本 token、工具调用元数据函数名与参数以及工具调用结果实时打印到 stdout。示例from 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其中还包含ToolCallDelta工具调用的增量片段index、tool_name、arguments、id与extra以及遵循 OpenAI 约定的finish_reason类型stop、length、tool_calls、content_filter等。若需自定义回调可以基于StreamingChunk自行编写处理函数。七、接入流水线与 ChatPromptBuilder 组合LiteLLMChatGenerator在流水线中最常见的位置是接在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)这条流水线的数据流是prompt_builder使用template含{{ country }}占位符的ChatMessage模板与template_variables渲染出具体消息通过pipe.connect(prompt_builder, llm)送入llm组件最终返回的res中包含replies。八、序列化支持组件实现了标准的to_dict/from_dictto_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - LiteLLMChatGeneratorto_dict将组件序列化为字典from_dict从字典反序列化出组件实例。这意味着组件可以被保存、传输并通过 Haystack 的 YAML / JSON 序列化机制配合Secret的受控序列化重建便于流水线的持久化与部署。注意Secret.from_token创建的密钥不可序列化环境变量形式的Secret才是可持久化流水线的推荐选择。九、常见问题与注意事项凭证缺失若既未传api_key对应提供商的标准环境变量也未设置LiteLLM 会在请求时报鉴权错误。优先使用环境变量方案。模型名格式务必使用provider/model-name前缀形式否则 LiteLLM 无法确定路由目标。默认模型为openai/gpt-4o适合快速验证。参数归一化generation_kwargs中目标提供商不支持的参数会被 LiteLLM 丢弃因此同一份参数集在不同提供商间迁移时行为可能略有差异建议按目标模型实测。工具支持边界函数调用依赖底层模型能力使用前需确认所选模型支持 function calling。自建代理企业内网或统一网关场景可设置api_base_url指向自托管的 LiteLLM Proxy实现集中式密钥管理与成本控制。十、深入阅读组件用户指南LiteLLMChatGenerator 使用文档组件 API 参考LiteLLM 集成 API对话消息数据类ChatMessage 文档凭证管理Secret 管理文档提示构建器ChatPromptBuilder 文档工具与工具集Tool 文档、Toolset 文档生成器总览pipeline-components/generators.mdx【免费下载链接】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），仅供参考