Haystack 接入 Hetzner 推理 APIHetznerChatGenerator 组件实战指南【免费下载链接】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/haystackHetznerChatGenerator 是 Haystack 生态中用于调用 Hetzner Inference API 的聊天生成组件它复用 OpenAI 兼容协议让你直接从欧洲数据中心调用 Qwen 系列开放权重模型并支持多模态输入、流式输出与工具调用。本文以 version-2.22 集成参考文档 为骨架结合 HetznerChatGenerator 组件指南 与 OpenAIChatGenerator 基类源码完整讲解该组件的模型清单、全部初始化参数、generation_kwargs 配置、序列化机制以及单独使用、多模态、流式和 Pipeline 组合四种实战用法。组件定位与核心特性HetznerChatGenerator位于集成包hetzner-haystack中类定义在haystack_integrations.components.generators.hetzner.chat.chat_generator模块。它直接继承 Haystack 核心的OpenAIChatGenerator源码见 haystack/components/generators/chat/openai.py这是因为 Hetzner Inference API 采用 OpenAI 兼容协议因此组件天然继承了 OpenAI 生态的参数体系与调用流程。该组件的核心能力调用 Hetzner 欧洲数据中心托管的开放权重模型默认接入地址为https://inference.hetzner.com/api/v1多模态输入托管的模型同时接受文本与图片因此可以在传给run的ChatMessage中携带ImageContent片段参数直通任何适用于 Hetzner chat completion API 的文本生成参数都可以通过__init__或run方法中的generation_kwargs直接传入在 Pipeline 中的典型位置位于ChatPromptBuilder之后接收messages列表输出replies列表均为ChatMessage对象。安装与环境准备使用该组件前需要安装独立集成包pip install hetzner-haystack组件的api_key参数默认从环境变量HETZNER_API_KEY读取export HETZNER_API_KEYyour_hetzner_inference_token也可以不依赖环境变量改用 Haystack 的密钥管理机制通过api_key参数显式传入Secret对象。支持的模型SUPPORTED_MODELS在 Hetzner Inference API 仍处于 experimental实验性阶段时组件内置了当前支持的模型白名单SUPPORTED_MODELS: list[str] [Qwen/Qwen3.6-35B-A3B-FP8, Qwen3.8-27B]关于这份清单需要注意三点模型选择随时间变化组件文档明确说明查询 API 的/v1/models端点返回的响应才是权威清单默认模型初始化时model默认为Qwen/Qwen3.6-35B-A3B-FP8白名单不做硬性拦截不在SUPPORTED_MODELS列表中的模型并不会被组件拒绝而是原样透传给 API。也就是说即使列表尚未更新你依然可以手动指定/v1/models返回的新模型名。这两个模型均提供 262,144 token 的超大上下文窗口且都支持文本与图片混合输入该细节见于 HetznerChatGenerator 组件指南。初始化参数详解__init__的完整签名如下来自 version-2.22 参考文档__init__( *, api_key: Secret Secret.from_env_var(HETZNER_API_KEY), model: str Qwen/Qwen3.6-35B-A3B-FP8, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None https://inference.hetzner.com/api/v1, generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None ) - None各参数含义与要点参数类型默认值说明api_keySecret环境变量HETZNER_API_KEYHetzner Inference API 令牌可用Secret.from_env_var或显式 Secret 传入modelstrQwen/Qwen3.6-35B-A3B-FP8使用的 chat completion 模型名参考SUPPORTED_MODELSstreaming_callbackStreamingCallbackT \| NoneNone流式回调函数收到新 token 时被调用回调参数为StreamingChunkapi_base_urlstr \| Nonehttps://inference.hetzner.com/api/v1Hetzner Inference API 基础地址generation_kwargsdict[str, Any] \| NoneNone传给模型的其他生成参数全部直通 Hetzner 端点toolsToolsType \| NoneNone供模型准备调用的Tool和/或Toolset对象列表也可传单个Toolset每个工具名必须唯一timeoutfloat \| NoneNoneHetzner API 调用的超时时间max_retriesint \| NoneNone遭遇内部错误后重试 Hetzner 的最大次数未设置时回退到OPENAI_MAX_RETRIES环境变量再否则为 5http_client_kwargsdict[str, Any] \| NoneNone用于配置自定义httpx.Client/httpx.AsyncClient的关键字参数字典generation_kwargs 常用参数由于 Hetzner API 与 OpenAI 兼容generation_kwargs支持与 OpenAIChatGenerator 相同的参数原文档重点列出的包括max_tokens输出文本可包含的最大 token 数上限temperature采样温度值越高模型越冒险。创意类应用可尝试 0.9答案明确的任务使用 0即 argmax 采样top_p核采样nucleus sampling模型只考虑累计概率质量达到top_p的 token 集合。例如 0.1 表示只考虑概率质量前 10% 的 tokenstream是否流式返回部分进度。开启后token 会以>from haystack_integrations.components.generators.hetzner import HetznerChatGenerator from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client HetznerChatGenerator() response client.run(messages) print(response)对应的输出结构示例{replies: [ChatMessage(_contentNatural Language Processing (NLP) is a branch of artificial intelligence that focuses on enabling computers to understand, interpret, and generate human language in a way that is meaningful and useful., _roleChatRole.ASSISTANT: assistant, _nameNone, _meta{model: Qwen/Qwen3.6-35B-A3B-FP8, index: 0, finish_reason: stop, usage: {prompt_tokens: 15, completion_tokens: 36, total_tokens: 51}})]}可以看到返回的ChatMessage元数据中携带了模型名model、序号index、终止原因finish_reason以及 token 用量统计usage方便后续记录与观测。组件指南中还提供了取用回复文本的写法response client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)]) print(response[replies][0].text)多模态输入由于托管模型同时接受文本与图片你可以直接构造包含ImageContent的ChatMessagefrom haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.hetzner import HetznerChatGenerator image ImageContent.from_url( https://cdn.hetzner.de/cdn/public/Uploads/Finnland_Luftaufnahme-v2.jpg ) client HetznerChatGenerator() response client.run( [ ChatMessage.from_user( content_parts[Describe this image in one sentence., image] ) ] ) print(response[replies][0].text)ImageContent的完整数据结构可参考 imagecontent.mdx。流式输出在初始化时传入streaming_callback即可开启流式输出。可以直接使用 Haystack 内置的print_streaming_chunk工具函数它会同时打印文本 token 与工具事件工具调用和工具结果from haystack.components.generators.utils import print_streaming_chunk from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.hetzner import HetznerChatGenerator client HetznerChatGenerator(streaming_callbackprint_streaming_chunk) client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)])从基类源码可以看出流式路径会将 OpenAI 兼容接口返回的Stream[ChatCompletionChunk]逐块转换为StreamingChunk含content、tool_calls、finish_reason、usage等字段后交给回调最后由_convert_streaming_chunks_to_chat_message汇总成一条完整的ChatMessage见 openai.py 中_handle_stream_response的实现。你也可以在run方法中临时传入streaming_callback覆盖初始化时的设置。在 Pipeline 中组合使用将HetznerChatGenerator接入 Haystack Pipeline 是生产环境中最常见的用法典型结构是「ChatPromptBuilder→HetznerChatGenerator」from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.hetzner import HetznerChatGenerator prompt_builder ChatPromptBuilder() llm HetznerChatGenerator() pipe Pipeline() pipe.add_component(builder, prompt_builder) pipe.add_component(llm, llm) pipe.connect(builder.prompt, llm.messages) messages [ ChatMessage.from_system(Give brief answers.), ChatMessage.from_user(Tell me about {{city}}), ] response pipe.run( data{ builder: {template: messages, template_variables: {city: Nuremberg}} }, ) print(response[llm][replies][0].text)这里messages必须是一组ChatMessage对象ChatMessage数据类包含消息内容、角色user/assistant/system/tool及可选元数据详见 chatmessage.mdx。若想让模型具备工具调用能力则把Tool对象、Toolset对象或两者的混合传入tools参数分别参考 tool.mdx 与 toolset.mdx。工具列表与generation_kwargs一样既可在初始化时设置也可在run调用时覆盖。源码视角继承自 OpenAIChatGenerator 的实现机制参考文档明确指出该组件的基类是OpenAIChatGenerator理解基类实现有助于掌握 Hetzner 集成的底层行为以下行号均指向 haystack/components/generators/chat/openai.py客户端构建warm_upwarm_up在首次run时自动触发第 234-246 行按需构建同步OpenAI客户端warm_up_async则构建AsyncOpenAI异步客户端。客户端参数由_client_kwargs第 216-227 行统一组装包括api_key、base_url、timeout与max_retries——这也解释了为何max_retries未设置时会读取OPENAI_MAX_RETRIES环境变量默认 5。请求组装_prepare_api_callrun中的generation_kwargs会与初始化时的generation_kwargs按 key 合并run传入的键优先第 513 行stream由是否存在流式回调自动推导传入response_format且非流式时会切换到 OpenAI 的parse端点第 549-554 行。工具处理传入的Tool/Toolset会被flatten_tools_or_toolsets展平并做重名检查再转换为 OpenAI 格式的{type: function, function: ...}定义第 525-539 行。响应转换非流式响应通过_convert_chat_completion_to_chat_message转为ChatMessage其中工具调用参数以 JSON 解析为ToolCall列表finish_reason为length或content_filter时会输出截断警告第 635-649 行。序列化to_dictto_dict将组件序列化为字典streaming_callback会经serialize_callable序列化Pydantic 类型的response_format会被转换为 OpenAI strict JSON schematools由serialize_tools_or_toolset处理对应的from_dict则完成逆向反序列化。因此 HetznerChatGenerator 天然支持 Haystack 的 YAML/字典序列化与 Pipeline 持久化机制。需要说明的是仓库当前核心代码仅包含 Haystack 本体hetzner-haystack集成包的具体子类实现位于独立集成仓库但由参考文档中 Bases:OpenAIChatGenerator 的声明可以推断该组件复用上述完整的 OpenAI 兼容调用链仅将默认api_base_url指向https://inference.hetzner.com/api/v1并将默认模型替换为 Qwen 系列。注意事项与使用前提实验性状态Hetzner Inference API 目前处于 experimental 阶段SUPPORTED_MODELS会随服务演进而调整部署前应以/v1/models端点返回为准地域与合规模型托管在 Hetzner 欧洲数据中心涉及数据驻留要求的场景需结合实际业务评估参数兼容性虽然 API 与 OpenAI 兼容但具体端点对参数的支持仍以 Hetzner 官方 chat completion API 文档为准流式结构化输出若同时使用stream与response_format后者必须传 JSON schema 而非 Pydantic 模型令牌管理262,144 token 的超大上下文窗口意味着输入长度配额宽松但仍建议结合max_tokens约束输出长度避免产生意外的费用与延迟。总体而言HetznerChatGenerator以极低的接入成本一个环境变量 一个 OpenAI 兼容客户端将 Haystack 的 Agentic Pipeline、RAG 与多模态应用快速桥接到欧洲托管的开源模型上是当前仓库中接入 OpenAI 兼容推理服务的代表性集成组件之一。【免费下载链接】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），仅供参考