Haystack Hugging Face API 集成参考Embedder、Chat Generator 与 TEI Ranker 的三后端接入实战【免费下载链接】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本文基于 Hugging Face API 集成 API 参考v2.21 编写系统讲解huggingface-api-haystack集成包提供的 6 个 Haystack 组件稠密/稀疏文档与文本 Embedder、聊天生成器HuggingFaceAPIChatGenerator以及基于 Text Embeddings Inference 的HuggingFaceTEIRanker。读完后你可以针对免费 Serverless Inference API、付费 Inference Endpoints、自托管 TEI/TGI 三类后端完成组件选型、参数配置、鉴权、流式与工具调用并把它接入 Haystack Pipeline 用于 RAG 索引与查询链路。一、集成包覆盖哪些组件该集成包huggingface-api-haystack围绕“通过 HTTP API 调用 Hugging Face 托管或自托管推理服务”这一主题提供六个组件全部支持同步run与异步run_async两套入口组件模块路径导入名职责HuggingFaceAPITextEmbedderhaystack_integrations.components.embedders.huggingface_api.text_embedder对单个字符串生成稠密向量HuggingFaceAPIDocumentEmbedderhaystack_integrations.components.embedders.huggingface_api.document_embedder对Document列表批量生成稠密向量HuggingFaceAPISparseDocumentEmbedder...huggingface_api.sparse_document_embedder基于 TEI 为Document生成稀疏向量sparse_embeddingHuggingFaceAPISparseTextEmbedder...huggingface_api.sparse_text_embedder基于 TEI 为单段文本生成SparseEmbeddingHuggingFaceAPIChatGeneratorhaystack_integrations.components.generators.huggingface_api.chat.chat_generator聊天补全支持多模态、流式与工具调用HuggingFaceTEIRankerhaystack_integrations.components.rankers.huggingface_api.ranker基于 TEI/rerank端点做语义重排需要注意这些组件的实现源码位于 Haystack 核心集成仓库haystack-core-integrations中本仓库承载的是它们的 API 参考文档、使用指南与相关发布说明。仓库内文档如 HuggingFaceTEIRanker 使用指南均标注包名为huggingface-api-haystack安装方式为pip install huggingface-api-haystack。二、三类推理后端与api_type的对应关系参考文档中每个组件的api_type参数都遵循同一套约定理解这张映射表是配置一切组件的前提api_type取值对应后端api_params必需键鉴权要求serverless_inference_apiHugging Face 免费 Serverless Inference APIInference Providersmodel模型 ID生成类组件建议再加provider需要 HF token有速率限制适合实验、不适合生产inference_endpoints付费 Inference Endpoints按小时计费的私有实例url端点地址需要 HF tokentext_embeddings_inference/text_generation_inference自托管 TEI嵌入/ TGI生成url服务地址如http://localhost:8080取决于服务端配置可选api_type既可以用枚举HFEmbeddingAPIType/HFGenerationAPIType表达也可以直接用等价字符串例如HFGenerationAPIType.SERVERLESS_INFERENCE_API与serverless_inference_api等价。鉴权Secret与环境变量所有组件的token参数默认值均为token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse)这意味着如果你没有显式传入token组件会依次尝试读取HF_API_TOKEN、HF_TOKEN环境变量strictFalse表示读不到时不报错而是允许为None。显式传 token 则推荐Secret.from_token(your-api-key)或Secret.from_env_var(HF_API_TOKEN)。token 在 Serverless Inference API 与 Inference Endpoints 两种场景下是必需的自托管 TEI/TGI 场景下是否需要取决于服务端配置。三、HuggingFaceAPITextEmbedder单文本稠密嵌入run(text: str) - dict[str, Any]返回键为embedding。完整构造签名摘自参考文档__init__( api_type: HFEmbeddingAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , truncate: bool | None True, normalize: bool | None False, ) - None参数要点prefix/suffix拼接到每条文本首/尾的字符串常用于注入指令前缀如 bge 系列模型的Represent this sentence for searching relevant passages:。truncate默认True将输入截断到模型支持的最大长度。仅对text_embeddings_inference或基于 TEI 后端的inference_endpoints生效serverless_inference_api下该参数被忽略。normalize默认False将向量归一化到单位长度生效范围与truncate相同。异常api_params缺少必需的model或url、url非法、api_type未知时抛ValueErrorrun时text非字符串抛TypeErrorAPI 返回向量维度异常抛ValueError。三种后端的完整示例保留参考文档原貌# 1) 免费 Serverless Inference API from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder from haystack.utils import Secret text_embedder HuggingFaceAPITextEmbedder( api_typeserverless_inference_api, api_params{model: BAAI/bge-small-en-v1.5}, tokenSecret.from_token(your-api-key), ) print(text_embedder.run(I love pizza!)) # {embedding: [0.017020374536514282, -0.023255806416273117, ...]} # 2) 付费 Inference Endpoints text_embedder HuggingFaceAPITextEmbedder( api_typeinference_endpoints, api_params{url: your-inference-endpoint-url}, tokenSecret.from_token(your-api-key), ) # 3) 自托管 TEI text_embedder HuggingFaceAPITextEmbedder( api_typetext_embeddings_inference, api_params{url: http://localhost:8080}, )组件还提供warm_up/warm_up_async分别创建同步、异步 HF 客户端与close/close_async关闭客户端以及to_dict/from_dict序列化接口用于 Pipeline 的 YAML 序列化与反序列化——这使其可以作为 Pipeline 图中的持久化节点。四、HuggingFaceAPIDocumentEmbedder批量文档嵌入与并发控制run(documents: list[Document]) - dict[str, list[Document]]返回带embedding字段的 Document 列表。相比文本 Embedder它多出批量与并发相关参数__init__( api_type: HFEmbeddingAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , truncate: bool | None True, normalize: bool | None False, batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, concurrency_limit: int 4, ) - Nonebatch_size默认 32每批处理的文档数决定了每次 HTTP 请求携带的文本量progress_bar默认True运行时显示进度条meta_fields_to_embed把指定 metadata 字段与正文一起嵌入embedding_separator默认\n是二者拼接分隔符——这是把“文档来源/标题”等元信息纳入向量的常用手段concurrency_limit默认 4run_async下允许的最大并发请求数。这一点可由发布说明佐证concurrency_limit 发布说明 明确该参数用于提升run_async的吞吐。from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder from haystack.utils import Secret from haystack.dataclasses import Document doc Document(contentI love pizza!) document_embedder HuggingFaceAPIDocumentEmbedder( api_typeserverless_inference_api, api_params{model: BAAI/bge-small-en-v1.5}, tokenSecret.from_token(your-api-key), ) result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]自托管 TEI 场景的等价配置只需把api_type换成text_embeddings_inference、api_params换成{url: http://localhost:8080}且可省去 token。该组件在 Pipeline 中的典型位置是索引链路中DocumentWriter之前详见 HuggingFaceAPIDocumentEmbedder 使用指南。五、稀疏嵌入HuggingFaceAPISparseDocumentEmbedder 与 HuggingFaceAPISparseTextEmbedder这两个组件面向关键词/稀疏检索场景要求后端是运行了稀疏嵌入模型的 TEI 服务并暴露/embed_sparse端点。两者都是 key-only 构造函数全参数均为关键字参数。HuggingFaceAPISparseDocumentEmbedder__init__( *, api_base_url: str http://localhost:8080, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, timeout: float | None 30.0, headers: dict[str, str] | None None, concurrency_limit: int 4, ) - Nonerun(documents)返回“设置了sparse_embedding字段的输入 Document 副本”即不原地修改输入from haystack import Document from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseDocumentEmbedder embedder HuggingFaceAPISparseDocumentEmbedder(api_base_urlhttp://localhost:8080) documents embedder.run([Document(contentSparse retrieval)])[documents] print(documents[0].sparse_embedding)HuggingFaceAPISparseTextEmbedder__init__( *, api_base_url: str http://localhost:8080, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , timeout: float | None 30.0, headers: dict[str, str] | None None, ) - Nonerun(text: str)/run_async(text: str)返回dict[str, SparseEmbedding]键为sparse_embedding。两个稀疏组件共同的异常语义api_base_url非法非 HTTP URL或数值参数非正时抛ValueError支持to_dict/from_dict序列化。timeout设为None表示禁用超时headers用于附加任意 HTTP 头如网关鉴权头。六、HuggingFaceAPIChatGenerator聊天补全、多模态、流式与工具调用输入输出均为 Haystack 的ChatMessage格式。构造签名__init__( api_type: HFGenerationAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), generation_kwargs: dict[str, Any] | None None, stop_words: list[str] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, ) - Noneapi_params除model/url外还接受providerServerless API 下推荐指定如together等推理提供方以及timeout、headers等 API 特有参数generation_kwargs透传给底层chat_completion的生成参数如max_tokens、temperature、top_pstreaming_callback流式回调与tools不能同时使用构造与run阶段都会抛ValueError工具名重复同样抛ValueErrortoolsTool列表或Toolset。参考文档明确提示Hugging Face API 与 TGI 对 tools 的支持“尚未完全打磨可能出现意外行为”选型时应以模型卡声明的 function calling 能力为准。from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType messages [ ChatMessage.from_system(\nYou are a helpful, respectful and honest assistant), ChatMessage.from_user(Whats Natural Language Processing?), ] # 枚举与字符串等价 api_type HFGenerationAPIType.SERVERLESS_INFERENCE_API api_type serverless_inference_api # equivalent generator HuggingFaceAPIChatGenerator( api_typeapi_type, api_params{model: Qwen/Qwen3.5-9B, provider: together}, tokenSecret.from_token(your-api-key), ) result generator.run(messages) # {replies: [ChatMessage(...)]}多模态文本 图像参考文档给出了 VLM 场景示例用ImageContent.from_file_path(...)支持文件路径、URL、base64 三种来源构造图像内容再与文本一起放进content_partsfrom haystack.dataclasses import ChatMessage, ImageContent image ImageContent.from_file_path(path/to/your/image.jpg) messages [ChatMessage.from_user(content_parts[Describe this image in detail, image])]该能力在发布说明中可得到印证add-image-support-huggingface-api-chat-generator 记录了为HuggingFaceAPIChatGenerator增加视觉-语言模型图像文本支持的变更后续的 reasoning 支持发布说明 则说明组件会提取并暴露推理reasoning内容。run / run_async 的覆盖语义run(messages, generation_kwargsNone, toolsNone, streaming_callbackNone)与run_async(...)语义一致后者可await返回{replies: list[ChatMessage]}。三个要点messages可以直接传字符串会被转换为单条 user 角色的ChatMessage列表运行期传入的generation_kwargs与初始化时的按键合并运行期提供的键优先初始化时设置而运行期未覆盖的键保留运行期传入的tools、streaming_callback会覆盖初始化时设置的同名参数。流式场景下返回的ChatMessagemeta 中会包含prompt_tokens与completion_tokens用量信息——内部会多请求一个携带 usage 数据的流式分块这一行为由 usage 相关发布说明 佐证。异步支持同样见 run_async 发布说明其内部依赖huggingface_hub的AsyncInferenceClient。自托管 TGI 的接入在 HuggingFaceAPIChatGenerator 使用指南 中给出了可复制的 Docker 命令modelHuggingFaceH4/zephyr-7b-beta volume$PWD/data # share a volume with the Docker container to avoid downloading weights every run docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data ghcr.io/huggingface/text-generation-inference:1.4 --model-id $model启动后组件侧配置为api_typetext_generation_inference、api_params{url: http://localhost:8080}。在 Pipeline 中该组件最常位于ChatPromptBuilder之后pipe.connect(prompt_builder.prompt, llm.messages)指南中给出了含模板变量{{location}}的完整 Pipeline 示例。七、HuggingFaceTEIRanker基于 TEI 的语义重排参考文档中该组件附带一个字符串枚举TruncationDirectionLEFT从文本头部截断、RIGHT从尾部截断用于输入超过模型长度限制时的截断方向控制。__init__( *, url: str, top_k: int 10, raw_scores: bool False, timeout: int | None 30, max_retries: int 3, retry_status_codes: list[int] | None None, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), ) - Noneurl必填TEI reranking 服务地址top_k默认 10最多返回的文档数run时可用同名参数临时覆盖raw_scores默认False是否在 API 请求体中附带原始分数timeout默认 30 秒与max_retries默认 3retry_status_codes为None时默认重试 HTTP 408、418、429、503——对自托管服务瞬时过载较友好端点支持自托管 TEI 与 Hugging Face Inference Endpoints。from haystack import Document from haystack.utils import Secret from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker reranker HuggingFaceTEIRanker( urlhttp://localhost:8080, top_k5, timeout30, tokenSecret.from_token(my_api_token), ) docs [ Document(contentThe capital of France is Paris), Document(contentThe capital of Germany is Berlin), ] result reranker.run(queryWhat is the capital of France?, documentsdocs) ranked_docs result[documents] print(ranked_docs) # {documents: [Document(id..., content: the capital of France is Paris, score: 0.9979767), # Document(id..., content: the capital of Germany is Berlin, score: 0.13982213)]}两个值得注意的行为细节均来自参考文档的方法说明去重run/run_async在排序前会按Document.id去重若文档带分数则保留分数最高的一条异常分层run在请求失败/响应报错时抛RuntimeError、响应结构非预期列表时抛TypeErrorrun_async则将网络层失败抛为httpx.RequestError其余一致。在 Pipeline 中的典型用法是接在 Retriever 之后。使用指南 给出了InMemoryBM25RetrieverHuggingFaceTEIRanker的完整示例from haystack import Document, Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker docs [ Document(contentParis is in France), Document(contentBerlin is in Germany), Document(contentLyon is in France), ] document_store InMemoryDocumentStore() document_store.write_documents(docs) retriever InMemoryBM25Retriever(document_storedocument_store) ranker HuggingFaceTEIRanker(urlhttp://localhost:8080) document_ranker_pipeline Pipeline() document_ranker_pipeline.add_component(instanceretriever, nameretriever) document_ranker_pipeline.add_component(instanceranker, nameranker) document_ranker_pipeline.connect(retriever.documents, ranker.documents) query Cities in France document_ranker_pipeline.run( data{ retriever: {query: query, top_k: 3}, ranker: {query: query, top_k: 2}, }, )注意Pipeline.run的data按组件名分发参数top_k在 retriever 与 ranker 上分别生效实现“先取 3 条、再精排到 2 条”的经典两段式检索。八、生命周期、序列化与异步模式的统一约定六个组件遵循同一套接口契约掌握了就可以互相迁移客户端生命周期warm_up()/warm_up_async()分别创建同步、异步客户端close()/close_async()关闭对应客户端。生成器组件的warm_up还会顺带预热warm up已配置的 tools。在 Pipeline 中Haystack 会在合适时机调用这些钩子独立使用时若长时间持有客户端建议显式close序列化全部提供to_dict()/from_dict(data)支持 Pipeline YAML 的保存与加载。历史发布说明如 fix-hf-api-serialization表明序列化行为曾经过修复反序列化得到的组件与手工构造的等价异步run_async与run参数、返回值一致。文档 Embedder 的异步路径通过concurrency_limit控制并发请求数属于批量吞吐的主要调优旋钮版本前提本文所有签名与默认值取自 version-2.21 参考文档对应 Haystack 2.21 时期的集成版本。当前主干文档如 最新版 Hugging Face API 参考 与各组件 mdx 指南可能包含更新特性升级前建议对照最新版本文档与huggingface-api-haystack的变更日志。九、选型与排错速查组件选型嵌入单条查询文本用HuggingFaceAPITextEmbedder嵌入文档列表用HuggingFaceAPIDocumentEmbedder批量 元字段嵌入稀疏索引用两个 Sparse 组件前提TEI 跑稀疏模型生成用HuggingFaceAPIChatGenerator重排用HuggingFaceTEIRanker。后端选型快速实验用serverless_inference_api有速率限制、需 token且truncate/normalize参数不生效生产用inference_endpoints或自托管 TEI/TGIDocker 部署参数可控可免 token。报错速查构造期ValueErrorapi_params缺model/url、URL 非法、api_type未知、稀疏组件 URL 非 HTTP、数值参数非正、tools与streaming_callback同用或工具重名运行期TypeErrortext/documents类型不符运行期ValueErrorAPI 返回向量形状异常运行期RuntimeErrorRanker请求失败或服务端报错httpx.RequestError仅在 Ranker 的run_async中出现在网络层。可深入的路径API 参考本文主体文档docs-website/reference_versioned_docs/version-2.21/integrations-api/huggingface_api.md组件使用指南HuggingFaceAPIDocumentEmbedder、HuggingFaceAPIChatGenerator、HuggingFaceTEIRanker行为变更佐证发布说明concurrency_limit、多模态支持、流式 usage、run_async【免费下载链接】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 Hugging Face API 集成参考：Embedder、Chat Generator 与 TEI Ranker 的三后端接入实战
Haystack Hugging Face API 集成参考Embedder、Chat Generator 与 TEI Ranker 的三后端接入实战【免费下载链接】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本文基于 Hugging Face API 集成 API 参考v2.21 编写系统讲解huggingface-api-haystack集成包提供的 6 个 Haystack 组件稠密/稀疏文档与文本 Embedder、聊天生成器HuggingFaceAPIChatGenerator以及基于 Text Embeddings Inference 的HuggingFaceTEIRanker。读完后你可以针对免费 Serverless Inference API、付费 Inference Endpoints、自托管 TEI/TGI 三类后端完成组件选型、参数配置、鉴权、流式与工具调用并把它接入 Haystack Pipeline 用于 RAG 索引与查询链路。一、集成包覆盖哪些组件该集成包huggingface-api-haystack围绕“通过 HTTP API 调用 Hugging Face 托管或自托管推理服务”这一主题提供六个组件全部支持同步run与异步run_async两套入口组件模块路径导入名职责HuggingFaceAPITextEmbedderhaystack_integrations.components.embedders.huggingface_api.text_embedder对单个字符串生成稠密向量HuggingFaceAPIDocumentEmbedderhaystack_integrations.components.embedders.huggingface_api.document_embedder对Document列表批量生成稠密向量HuggingFaceAPISparseDocumentEmbedder...huggingface_api.sparse_document_embedder基于 TEI 为Document生成稀疏向量sparse_embeddingHuggingFaceAPISparseTextEmbedder...huggingface_api.sparse_text_embedder基于 TEI 为单段文本生成SparseEmbeddingHuggingFaceAPIChatGeneratorhaystack_integrations.components.generators.huggingface_api.chat.chat_generator聊天补全支持多模态、流式与工具调用HuggingFaceTEIRankerhaystack_integrations.components.rankers.huggingface_api.ranker基于 TEI/rerank端点做语义重排需要注意这些组件的实现源码位于 Haystack 核心集成仓库haystack-core-integrations中本仓库承载的是它们的 API 参考文档、使用指南与相关发布说明。仓库内文档如 HuggingFaceTEIRanker 使用指南均标注包名为huggingface-api-haystack安装方式为pip install huggingface-api-haystack。二、三类推理后端与api_type的对应关系参考文档中每个组件的api_type参数都遵循同一套约定理解这张映射表是配置一切组件的前提api_type取值对应后端api_params必需键鉴权要求serverless_inference_apiHugging Face 免费 Serverless Inference APIInference Providersmodel模型 ID生成类组件建议再加provider需要 HF token有速率限制适合实验、不适合生产inference_endpoints付费 Inference Endpoints按小时计费的私有实例url端点地址需要 HF tokentext_embeddings_inference/text_generation_inference自托管 TEI嵌入/ TGI生成url服务地址如http://localhost:8080取决于服务端配置可选api_type既可以用枚举HFEmbeddingAPIType/HFGenerationAPIType表达也可以直接用等价字符串例如HFGenerationAPIType.SERVERLESS_INFERENCE_API与serverless_inference_api等价。鉴权Secret与环境变量所有组件的token参数默认值均为token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse)这意味着如果你没有显式传入token组件会依次尝试读取HF_API_TOKEN、HF_TOKEN环境变量strictFalse表示读不到时不报错而是允许为None。显式传 token 则推荐Secret.from_token(your-api-key)或Secret.from_env_var(HF_API_TOKEN)。token 在 Serverless Inference API 与 Inference Endpoints 两种场景下是必需的自托管 TEI/TGI 场景下是否需要取决于服务端配置。三、HuggingFaceAPITextEmbedder单文本稠密嵌入run(text: str) - dict[str, Any]返回键为embedding。完整构造签名摘自参考文档__init__( api_type: HFEmbeddingAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , truncate: bool | None True, normalize: bool | None False, ) - None参数要点prefix/suffix拼接到每条文本首/尾的字符串常用于注入指令前缀如 bge 系列模型的Represent this sentence for searching relevant passages:。truncate默认True将输入截断到模型支持的最大长度。仅对text_embeddings_inference或基于 TEI 后端的inference_endpoints生效serverless_inference_api下该参数被忽略。normalize默认False将向量归一化到单位长度生效范围与truncate相同。异常api_params缺少必需的model或url、url非法、api_type未知时抛ValueErrorrun时text非字符串抛TypeErrorAPI 返回向量维度异常抛ValueError。三种后端的完整示例保留参考文档原貌# 1) 免费 Serverless Inference API from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder from haystack.utils import Secret text_embedder HuggingFaceAPITextEmbedder( api_typeserverless_inference_api, api_params{model: BAAI/bge-small-en-v1.5}, tokenSecret.from_token(your-api-key), ) print(text_embedder.run(I love pizza!)) # {embedding: [0.017020374536514282, -0.023255806416273117, ...]} # 2) 付费 Inference Endpoints text_embedder HuggingFaceAPITextEmbedder( api_typeinference_endpoints, api_params{url: your-inference-endpoint-url}, tokenSecret.from_token(your-api-key), ) # 3) 自托管 TEI text_embedder HuggingFaceAPITextEmbedder( api_typetext_embeddings_inference, api_params{url: http://localhost:8080}, )组件还提供warm_up/warm_up_async分别创建同步、异步 HF 客户端与close/close_async关闭客户端以及to_dict/from_dict序列化接口用于 Pipeline 的 YAML 序列化与反序列化——这使其可以作为 Pipeline 图中的持久化节点。四、HuggingFaceAPIDocumentEmbedder批量文档嵌入与并发控制run(documents: list[Document]) - dict[str, list[Document]]返回带embedding字段的 Document 列表。相比文本 Embedder它多出批量与并发相关参数__init__( api_type: HFEmbeddingAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , truncate: bool | None True, normalize: bool | None False, batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, concurrency_limit: int 4, ) - Nonebatch_size默认 32每批处理的文档数决定了每次 HTTP 请求携带的文本量progress_bar默认True运行时显示进度条meta_fields_to_embed把指定 metadata 字段与正文一起嵌入embedding_separator默认\n是二者拼接分隔符——这是把“文档来源/标题”等元信息纳入向量的常用手段concurrency_limit默认 4run_async下允许的最大并发请求数。这一点可由发布说明佐证concurrency_limit 发布说明 明确该参数用于提升run_async的吞吐。from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder from haystack.utils import Secret from haystack.dataclasses import Document doc Document(contentI love pizza!) document_embedder HuggingFaceAPIDocumentEmbedder( api_typeserverless_inference_api, api_params{model: BAAI/bge-small-en-v1.5}, tokenSecret.from_token(your-api-key), ) result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]自托管 TEI 场景的等价配置只需把api_type换成text_embeddings_inference、api_params换成{url: http://localhost:8080}且可省去 token。该组件在 Pipeline 中的典型位置是索引链路中DocumentWriter之前详见 HuggingFaceAPIDocumentEmbedder 使用指南。五、稀疏嵌入HuggingFaceAPISparseDocumentEmbedder 与 HuggingFaceAPISparseTextEmbedder这两个组件面向关键词/稀疏检索场景要求后端是运行了稀疏嵌入模型的 TEI 服务并暴露/embed_sparse端点。两者都是 key-only 构造函数全参数均为关键字参数。HuggingFaceAPISparseDocumentEmbedder__init__( *, api_base_url: str http://localhost:8080, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, timeout: float | None 30.0, headers: dict[str, str] | None None, concurrency_limit: int 4, ) - Nonerun(documents)返回“设置了sparse_embedding字段的输入 Document 副本”即不原地修改输入from haystack import Document from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPISparseDocumentEmbedder embedder HuggingFaceAPISparseDocumentEmbedder(api_base_urlhttp://localhost:8080) documents embedder.run([Document(contentSparse retrieval)])[documents] print(documents[0].sparse_embedding)HuggingFaceAPISparseTextEmbedder__init__( *, api_base_url: str http://localhost:8080, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), prefix: str , suffix: str , timeout: float | None 30.0, headers: dict[str, str] | None None, ) - Nonerun(text: str)/run_async(text: str)返回dict[str, SparseEmbedding]键为sparse_embedding。两个稀疏组件共同的异常语义api_base_url非法非 HTTP URL或数值参数非正时抛ValueError支持to_dict/from_dict序列化。timeout设为None表示禁用超时headers用于附加任意 HTTP 头如网关鉴权头。六、HuggingFaceAPIChatGenerator聊天补全、多模态、流式与工具调用输入输出均为 Haystack 的ChatMessage格式。构造签名__init__( api_type: HFGenerationAPIType | str, api_params: dict[str, str], token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), generation_kwargs: dict[str, Any] | None None, stop_words: list[str] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None, ) - Noneapi_params除model/url外还接受providerServerless API 下推荐指定如together等推理提供方以及timeout、headers等 API 特有参数generation_kwargs透传给底层chat_completion的生成参数如max_tokens、temperature、top_pstreaming_callback流式回调与tools不能同时使用构造与run阶段都会抛ValueError工具名重复同样抛ValueErrortoolsTool列表或Toolset。参考文档明确提示Hugging Face API 与 TGI 对 tools 的支持“尚未完全打磨可能出现意外行为”选型时应以模型卡声明的 function calling 能力为准。from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret from haystack_integrations.common.huggingface_api.utils import HFGenerationAPIType messages [ ChatMessage.from_system(\nYou are a helpful, respectful and honest assistant), ChatMessage.from_user(Whats Natural Language Processing?), ] # 枚举与字符串等价 api_type HFGenerationAPIType.SERVERLESS_INFERENCE_API api_type serverless_inference_api # equivalent generator HuggingFaceAPIChatGenerator( api_typeapi_type, api_params{model: Qwen/Qwen3.5-9B, provider: together}, tokenSecret.from_token(your-api-key), ) result generator.run(messages) # {replies: [ChatMessage(...)]}多模态文本 图像参考文档给出了 VLM 场景示例用ImageContent.from_file_path(...)支持文件路径、URL、base64 三种来源构造图像内容再与文本一起放进content_partsfrom haystack.dataclasses import ChatMessage, ImageContent image ImageContent.from_file_path(path/to/your/image.jpg) messages [ChatMessage.from_user(content_parts[Describe this image in detail, image])]该能力在发布说明中可得到印证add-image-support-huggingface-api-chat-generator 记录了为HuggingFaceAPIChatGenerator增加视觉-语言模型图像文本支持的变更后续的 reasoning 支持发布说明 则说明组件会提取并暴露推理reasoning内容。run / run_async 的覆盖语义run(messages, generation_kwargsNone, toolsNone, streaming_callbackNone)与run_async(...)语义一致后者可await返回{replies: list[ChatMessage]}。三个要点messages可以直接传字符串会被转换为单条 user 角色的ChatMessage列表运行期传入的generation_kwargs与初始化时的按键合并运行期提供的键优先初始化时设置而运行期未覆盖的键保留运行期传入的tools、streaming_callback会覆盖初始化时设置的同名参数。流式场景下返回的ChatMessagemeta 中会包含prompt_tokens与completion_tokens用量信息——内部会多请求一个携带 usage 数据的流式分块这一行为由 usage 相关发布说明 佐证。异步支持同样见 run_async 发布说明其内部依赖huggingface_hub的AsyncInferenceClient。自托管 TGI 的接入在 HuggingFaceAPIChatGenerator 使用指南 中给出了可复制的 Docker 命令modelHuggingFaceH4/zephyr-7b-beta volume$PWD/data # share a volume with the Docker container to avoid downloading weights every run docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data ghcr.io/huggingface/text-generation-inference:1.4 --model-id $model启动后组件侧配置为api_typetext_generation_inference、api_params{url: http://localhost:8080}。在 Pipeline 中该组件最常位于ChatPromptBuilder之后pipe.connect(prompt_builder.prompt, llm.messages)指南中给出了含模板变量{{location}}的完整 Pipeline 示例。七、HuggingFaceTEIRanker基于 TEI 的语义重排参考文档中该组件附带一个字符串枚举TruncationDirectionLEFT从文本头部截断、RIGHT从尾部截断用于输入超过模型长度限制时的截断方向控制。__init__( *, url: str, top_k: int 10, raw_scores: bool False, timeout: int | None 30, max_retries: int 3, retry_status_codes: list[int] | None None, token: Secret | None Secret.from_env_var([HF_API_TOKEN, HF_TOKEN], strictFalse), ) - Noneurl必填TEI reranking 服务地址top_k默认 10最多返回的文档数run时可用同名参数临时覆盖raw_scores默认False是否在 API 请求体中附带原始分数timeout默认 30 秒与max_retries默认 3retry_status_codes为None时默认重试 HTTP 408、418、429、503——对自托管服务瞬时过载较友好端点支持自托管 TEI 与 Hugging Face Inference Endpoints。from haystack import Document from haystack.utils import Secret from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker reranker HuggingFaceTEIRanker( urlhttp://localhost:8080, top_k5, timeout30, tokenSecret.from_token(my_api_token), ) docs [ Document(contentThe capital of France is Paris), Document(contentThe capital of Germany is Berlin), ] result reranker.run(queryWhat is the capital of France?, documentsdocs) ranked_docs result[documents] print(ranked_docs) # {documents: [Document(id..., content: the capital of France is Paris, score: 0.9979767), # Document(id..., content: the capital of Germany is Berlin, score: 0.13982213)]}两个值得注意的行为细节均来自参考文档的方法说明去重run/run_async在排序前会按Document.id去重若文档带分数则保留分数最高的一条异常分层run在请求失败/响应报错时抛RuntimeError、响应结构非预期列表时抛TypeErrorrun_async则将网络层失败抛为httpx.RequestError其余一致。在 Pipeline 中的典型用法是接在 Retriever 之后。使用指南 给出了InMemoryBM25RetrieverHuggingFaceTEIRanker的完整示例from haystack import Document, Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker docs [ Document(contentParis is in France), Document(contentBerlin is in Germany), Document(contentLyon is in France), ] document_store InMemoryDocumentStore() document_store.write_documents(docs) retriever InMemoryBM25Retriever(document_storedocument_store) ranker HuggingFaceTEIRanker(urlhttp://localhost:8080) document_ranker_pipeline Pipeline() document_ranker_pipeline.add_component(instanceretriever, nameretriever) document_ranker_pipeline.add_component(instanceranker, nameranker) document_ranker_pipeline.connect(retriever.documents, ranker.documents) query Cities in France document_ranker_pipeline.run( data{ retriever: {query: query, top_k: 3}, ranker: {query: query, top_k: 2}, }, )注意Pipeline.run的data按组件名分发参数top_k在 retriever 与 ranker 上分别生效实现“先取 3 条、再精排到 2 条”的经典两段式检索。八、生命周期、序列化与异步模式的统一约定六个组件遵循同一套接口契约掌握了就可以互相迁移客户端生命周期warm_up()/warm_up_async()分别创建同步、异步客户端close()/close_async()关闭对应客户端。生成器组件的warm_up还会顺带预热warm up已配置的 tools。在 Pipeline 中Haystack 会在合适时机调用这些钩子独立使用时若长时间持有客户端建议显式close序列化全部提供to_dict()/from_dict(data)支持 Pipeline YAML 的保存与加载。历史发布说明如 fix-hf-api-serialization表明序列化行为曾经过修复反序列化得到的组件与手工构造的等价异步run_async与run参数、返回值一致。文档 Embedder 的异步路径通过concurrency_limit控制并发请求数属于批量吞吐的主要调优旋钮版本前提本文所有签名与默认值取自 version-2.21 参考文档对应 Haystack 2.21 时期的集成版本。当前主干文档如 最新版 Hugging Face API 参考 与各组件 mdx 指南可能包含更新特性升级前建议对照最新版本文档与huggingface-api-haystack的变更日志。九、选型与排错速查组件选型嵌入单条查询文本用HuggingFaceAPITextEmbedder嵌入文档列表用HuggingFaceAPIDocumentEmbedder批量 元字段嵌入稀疏索引用两个 Sparse 组件前提TEI 跑稀疏模型生成用HuggingFaceAPIChatGenerator重排用HuggingFaceTEIRanker。后端选型快速实验用serverless_inference_api有速率限制、需 token且truncate/normalize参数不生效生产用inference_endpoints或自托管 TEI/TGIDocker 部署参数可控可免 token。报错速查构造期ValueErrorapi_params缺model/url、URL 非法、api_type未知、稀疏组件 URL 非 HTTP、数值参数非正、tools与streaming_callback同用或工具重名运行期TypeErrortext/documents类型不符运行期ValueErrorAPI 返回向量形状异常运行期RuntimeErrorRanker请求失败或服务端报错httpx.RequestError仅在 Ranker 的run_async中出现在网络层。可深入的路径API 参考本文主体文档docs-website/reference_versioned_docs/version-2.21/integrations-api/huggingface_api.md组件使用指南HuggingFaceAPIDocumentEmbedder、HuggingFaceAPIChatGenerator、HuggingFaceTEIRanker行为变更佐证发布说明concurrency_limit、多模态支持、流式 usage、run_async【免费下载链接】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），仅供参考
