Haystack 与 vLLM 集成实战基于 OpenAI 兼容接口接入文档嵌入、文本嵌入、Chat 生成与 Rerank 排序【免费下载链接】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 官方 vLLM 集成haystack-integrations中的components.embedders.vllm、components.generators.vllm、components.rankers.vllm三个模块展开系统讲解如何在本机或远程启动 vLLM 服务并在 Haystack 管道中通过VLLMDocumentEmbedder、VLLMTextEmbedder、VLLMChatGenerator、VLLMRanker四个组件完成文档向量化、查询向量化、对话生成与重排序。读完本文你将掌握每个组件的完整初始化参数、run/run_async调用方式、vLLM 私有参数如truncate_prompt_tokens、top_k、repetition_penalty的透传方法以及工具调用tool calling与推理模型reasoning models的端到端配置方案可直接落地到 RAG、语义检索与 Agent 工作流中。一、vLLM 集成的整体架构与设计思路vLLM 集成遵循一条统一的设计原则Haystack 组件不直接与 vLLM 内部推理引擎打交道而是通过 vLLM 暴露的 OpenAI 兼容 HTTP 接口进行通信。这意味着四个组件都以api_base_url定位服务地址默认值为http://localhost:8000/v1与 vLLM 默认的 OpenAI 兼容服务端口一致认证统一走api_key默认从VLLM_API_KEY环境变量读取仅当 vLLM 服务以--api-key启动时才需要底层 HTTP 客户端基于httpx支持通过http_client_kwargs注入自定义httpx.Client/httpx.AsyncClient嵌入类组件Embedder与 Chat 生成组件同时提供同步run与异步run_async两种入口便于在异步管道AsyncPipeline中使用extra_parameters/generation_kwargs[extra_body]机制承担vLLM 私有能力透传的职责使组件能够使用标准 OpenAI API 之外的服务端特性。从 Haystack 核心库看这些组件产出的数据对象Document.embedding、ChatMessage、StreamingChunk均由核心数据类定义见 document.py、chat_message.py 与 streaming_chunk.py因此集成组件可以无缝嵌入任何 Haystack 管道。二、VLLMDocumentEmbedder批量文档嵌入VLLMDocumentEmbedder位于haystack_integrations.components.embedders.vllm.document_embedder模块用于对一批 Document计算向量并将结果写入每个 Document 的embedding字段即 document.py 中定义的Document.embedding。2.1 启动 vLLM 服务使用前必须先启动一个加载了嵌入模型的 vLLM 服务vllm serve google/embeddinggemma-300m该命令会监听8000端口并提供 OpenAI 兼容的 Embeddings API。服务端更多启动选项如--port、--api-key、量化参数等可查阅 vLLM 官方 CLI 文档。2.2 基本用法from haystack import Document from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder doc Document(contentI love pizza!) document_embedder VLLMDocumentEmbedder(modelgoogle/embeddinggemma-300m) result document_embedder.run([doc]) print(result[documents][0].embedding)run接收list[Document]返回字典包含两个键documents输入 Document 列表其embedding字段已被填充meta模型使用情况信息如 token 用量等。run_async(documents)提供完全相同的语义只是以异步方式执行。2.3 透传 vLLM 私有参数对于标准 OpenAI Embeddings API 之外的 vLLM 特有参数通过extra_parameters字典传入组件会将其作为extra_body转发给服务端document_embedder VLLMDocumentEmbedder( modelgoogle/embeddinggemma-300m, extra_parameters{truncate_prompt_tokens: 256, truncation_side: right}, )典型 vLLM 私有参数包括truncate_prompt_tokens超长输入从哪一侧截断到多少 token与truncation_side截断方向。2.4 完整初始化参数__init__签名全部为关键字参数如下__init__( *, model: str, api_key: Secret | None Secret.from_env_var(VLLM_API_KEY, strictFalse), api_base_url: str http://localhost:8000/v1, prefix: str , suffix: str , dimensions: int | None None, batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None, raise_on_failure: bool False, extra_parameters: dict[str, Any] | None None ) - None各参数语义与实操要点参数类型/默认值说明modelstr必填vLLM 服务所加载的模型名须与vllm serve指定的模型一致api_keySecret \| None默认读VLLM_API_KEY环境变量strictFalse未设置不报错仅当服务端以--api-key启动时需要api_base_urlstr默认http://localhost:8000/v1vLLM 服务的基础 URL远程部署时改为对应地址prefix/suffixstr默认空串分别添加到每段待嵌入文本开头/结尾的字符串常用于按模型要求的提示模板包裹文本dimensionsint \| None输出向量的维度数仅支持经过 Matryoshka Representation Learning套娃表示学习训练的模型可据此裁剪输出维度以节省存储batch_sizeint默认32一次请求编码的 Document 数量progress_barbool默认True是否显示批处理进度条meta_fields_to_embedlist[str] \| None需要拼接到文档正文上一并嵌入的 meta 字段名列表如标题、作者等embedding_separatorstr默认\n拼接 meta 字段与正文时使用的分隔符timeoutfloat \| None单次客户端调用的超时秒数不设置则采用 OpenAI 客户端默认值max_retriesint \| None失败请求的最大重试次数不设置则采用 OpenAI 客户端默认值http_client_kwargsdict[str, Any] \| None构造自定义httpx.Client/httpx.AsyncClient的关键字参数如代理、TLS 配置raise_on_failurebool默认False为True时嵌入请求失败直接抛异常为False时记录错误日志并继续处理剩余文档extra_parametersdict[str, Any] \| None以extra_body形式透传给 vLLM 嵌入端点的私有参数生命周期方法warm_up()创建底层 OpenAI 客户端应在管道warm_up()阶段被调用Haystack 管道会自动触发各组件warm_up。三、VLLMTextEmbedder单条文本嵌入VLLMTextEmbedder位于haystack_integrations.components.embedders.vllm.text_embedder模块面向RAG 查询侧将单条查询字符串编码为向量供相似度检索使用。它与VLLMDocumentEmbedder共用同一套服务端前置条件同样执行vllm serve google/embeddinggemma-300m启动服务。3.1 基本用法from haystack_integrations.components.embedders.vllm import VLLMTextEmbedder text_embedder VLLMTextEmbedder(modelgoogle/embeddinggemma-300m) print(text_embedder.run(I love pizza!))run(text: str)返回字典embedding输入文本的向量list[float]meta模型使用情况信息。run_async(text: str)语义相同异步执行。3.2 透传 vLLM 私有参数与 Document 版一致通过extra_parameters透传text_embedder VLLMTextEmbedder( modelgoogle/embeddinggemma-300m, extra_parameters{truncate_prompt_tokens: 256, truncation_side: right}, )3.3 完整初始化参数__init__( *, model: str, api_key: Secret | None Secret.from_env_var(VLLM_API_KEY, strictFalse), api_base_url: str http://localhost:8000/v1, prefix: str , suffix: str , dimensions: int | None None, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None, extra_parameters: dict[str, Any] | None None ) - None各参数含义与VLLMDocumentEmbedder对应项一致差异在于没有batch_size、progress_bar、meta_fields_to_embed、embedding_separator、raise_on_failure等批处理相关参数因为只处理单条文本model的示例值可以是intfloat/e5-mistral-7b-instruct这类需要按提示模板加prefix/suffix的指令型嵌入模型extra_parameters支持范围更广文档给出的示例还包括additional_data、use_activation等 vLLM 嵌入端点私有参数。四、VLLMChatGenerator对话生成、工具调用与推理模型VLLMChatGenerator位于haystack_integrations.components.generators.vllm.chat.chat_generator模块用于生成聊天补全chat completions是四个组件中能力最丰富的支持流式输出、工具调用tool calling、推理模型reasoning models、结构化输出与序列化。4.1 启动 vLLM 服务基础启动命令vllm serve Qwen/Qwen3-4B-Instruct-2507针对三类特殊场景启动命令需要附加参数推理模型如 Qwen3 系列需要指定对应的 reasoning parservllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3工具调用场景必须同时开启--enable-auto-tool-choice并指定--tool-call-parservllm serve Qwen/Qwen3-0.6B --enable-auto-tool-choice --tool-call-parser hermes注意可用的 tool call parser 取决于模型本身完整的 parser 列表以 vLLM 官方工具调用文档为准。4.2 基本用法from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.vllm import VLLMChatGenerator generator VLLMChatGenerator( modelQwen/Qwen3-0.6B, generation_kwargs{max_tokens: 512, temperature: 0.7}, ) messages [ChatMessage.from_user(Whats Natural Language Processing?)] response generator.run(messagesmessages) print(response[replies][0].text)关键点消息对象使用 Haystack 核心数据类ChatMessage由 chat_message.py 定义可通过from_user、from_system、from_assistant、from_tool等类方法构造内部支持文本、工具调用ToolCall、工具结果ToolCallResult、图片/文件与推理内容等多种内容单元run的messages参数既可以是list[ChatMessage]也可以是普通字符串——字符串会被自动转换为一个 role 为 user 的ChatMessage返回值只含一个键replies生成的回复ChatMessage列表可通过.text取正文。4.3 透传 vLLM 私有参数与嵌入组件不同Chat 生成器的 vLLM 私有参数放在generation_kwargs的extra_body子字典中from haystack_integrations.components.generators.vllm import VLLMChatGenerator generator VLLMChatGenerator( modelQwen/Qwen3-0.6B, generation_kwargs{ max_tokens: 512, extra_body: { top_k: 50, min_tokens: 10, repetition_penalty: 1.1, }, }, )generation_kwargs中支持的标准 OpenAI 参数包括max_tokens生成的最大 token 数temperature采样温度top_p核采样nucleus sampling参数n每个提示生成的补全数量stop一个或多个停止序列模型遇到后停止生成response_formatJSON Schema 或 Pydantic 模型用于强制约束响应结构结构化输出。extra_body则承载 vLLM 私有参数如top_k、min_tokens、repetition_penalty。4.4 工具调用Tool Calling服务端以--enable-auto-tool-choice --tool-call-parser hermes启动后即可为模型注册 Haystack 工具。工具通过tool装饰器定义于 from_function.py从普通函数生成from haystack.dataclasses import ChatMessage from haystack.tools import tool from haystack_integrations.components.generators.vllm import VLLMChatGenerator tool def weather(city: str) - str: Get the weather in a given city. return fThe weather in {city} is sunny generator VLLMChatGenerator(modelQwen/Qwen3-0.6B, tools[weather]) messages [ChatMessage.from_user(What is the weather in Paris?)] response generator.run(messagesmessages) print(response[replies][0].tool_calls)要点tools参数接受ToolsType可以是 Tool/Toolset 对象列表也可以是单个 Toolset每个工具名称必须唯一模型返回的调用意向可通过ChatMessage.tool_calls属性读取见 chat_message.py 中的ToolCall类包含tool_name、arguments、id等字段拿到后由应用自行执行工具并回填结果并非所有模型都支持工具调用请以具体模型的 vLLM 支持情况为准。4.5 推理模型Reasoning Models服务端以--reasoning-parser qwen3启动后回复中的推理过程与最终答案会分开返回from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.vllm import VLLMChatGenerator generator VLLMChatGenerator(modelQwen/Qwen3-0.6B) messages [ChatMessage.from_user(Solve step by step: what is 15 * 37?)] response generator.run(messagesmessages) reply response[replies][0] if reply.reasoning: print(Reasoning:, reply.reasoning.reasoning_text) print(Answer:, reply.text)ChatMessage的reasoning属性返回包含reasoning_text字段的推理内容对象该结构同样由 chat_message.py 定义。应用可根据需要选择展示、隐藏或继续引用推理文本。4.6 完整初始化参数与序列化__init__( *, model: str, api_key: Secret | None Secret.from_env_var(VLLM_API_KEY, strictFalse), streaming_callback: StreamingCallbackT | None None, api_base_url: str http://localhost:8000/v1, generation_kwargs: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None, tools: ToolsType | None None, http_client_kwargs: dict[str, Any] | None None ) - None参数说明modelvLLM 服务所加载的模型名如Qwen/Qwen3-0.6Bapi_key默认读VLLM_API_KEY环境变量仅服务端启用--api-key时需要streaming_callback流式回调函数每收到一个新 token 即被调用回调参数为StreamingChunk定义见 streaming_chunk.pyapi_base_urlvLLM 服务基础 URL默认http://localhost:8000/v1generation_kwargs生成参数直接发送给 vLLM OpenAI 兼容端点详见 4.3 节timeout/max_retries客户端超时与重试不设置则用 OpenAI 客户端默认值tools可调用工具列表/Toolset模型据此准备调用http_client_kwargs自定义httpx客户端的关键字参数生命周期与序列化warm_up()创建 OpenAI 客户端并预热工具to_dict()将组件序列化为字典from_dict(data)从字典反序列化恢复组件实例——这两个方法保证组件可以在 Haystack 的Pipeline/Pipeline.from_dict中保存与加载。4.7 run 与 run_async 的运行时覆盖能力run与run_async签名一致run( messages: list[ChatMessage] | str, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None ) - dict[str, list[ChatMessage]]generation_kwargs在运行时传入时会覆盖初始化时设置的同名参数便于在同一组件实例上按请求动态调整采样配置tools在运行时传入时会覆盖初始化时的工具集合run_async的streaming_callback必须为协程coroutine返回字典仅含replies键生成回复的ChatMessage列表。五、VLLMRanker基于 /rerank 端点的文档重排序VLLMRanker位于haystack_integrations.components.rankers.vllm.ranker模块使用 vLLM 暴露的/rerank端点按查询与文档的相似度对文档排序适合作为 RAG 管道检索后的精排环节。5.1 启动 vLLM 服务使用前需启动加载了 reranker 模型的服务vllm serve BAAI/bge-reranker-base注意这里使用的是 vLLM 的 rerankscoring能力因此必须加载支持 rerank 的模型如 BGE Reranker 系列支持的模型列表以 vLLM 官方文档为准。5.2 基本用法from haystack import Document from haystack_integrations.components.rankers.vllm import VLLMRanker ranker VLLMRanker(modelBAAI/bge-reranker-base) docs [ Document(contentThe capital of Brazil is Brasilia.), Document(contentThe capital of France is Paris.), ] result ranker.run(queryWhat is the capital of France?, documentsdocs) print(result[documents][0].content)run(query, documents, top_kNone, score_thresholdNone)返回字典documents按相关性从高到低排序的 Document 列表meta模型与用量信息。run_async语义相同。两者在top_k不合法非正数时都会抛出ValueError。5.3 透传 vLLM 私有参数与嵌入组件不同extra_parameters在这里会被合并进发送到/rerank端点的请求体ranker VLLMRanker( modelBAAI/bge-reranker-base, extra_parameters{truncate_prompt_tokens: 256}, )5.4 完整初始化参数__init__( *, model: str, api_key: Secret | None Secret.from_env_var(VLLM_API_KEY, strictFalse), api_base_url: str http://localhost:8000/v1, top_k: int | None None, score_threshold: float | None None, meta_fields_to_embed: list[str] | None None, meta_data_separator: str \n, http_client_kwargs: dict[str, Any] | None None, extra_parameters: dict[str, Any] | None None ) - None参数类型/默认值说明modelstr必填vLLM 服务加载的 reranker 模型名api_keySecret \| None默认读VLLM_API_KEY服务端启用--api-key时需要api_base_urlstr默认http://localhost:8000/v1vLLM 服务基础 URLtop_kint \| None最多返回的 Document 数为None时返回全部文档score_thresholdfloat \| None相关性得分低于该值的文档被丢弃在top_k之后应用因此最终返回可能少于top_k条meta_fields_to_embedlist[str] \| None重排前需要拼接到文档正文上的 meta 字段列表meta_data_separatorstr默认\n拼接 meta 字段与正文的分隔符http_client_kwargsdict[str, Any] \| None自定义httpx客户端参数extra_parametersdict[str, Any] \| None合并进/rerank请求体的私有参数如truncate_prompt_tokens生命周期方法warm_up()创建 httpx 客户端Reranker 直接走 HTTP不使用 OpenAI 客户端初始化时若top_k不为正数会抛出ValueErrorrun时传入的top_k/score_threshold会覆盖初始化值。六、在 Haystack 管道中的组合实践四个组件可以组合成典型的 RAG 管道。例如一个文档索引 检索 精排 生成的完整链路可以这样组织from haystack import Document, Pipeline from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.embedders.vllm import VLLMDocumentEmbedder, VLLMTextEmbedder from haystack_integrations.components.rankers.vllm import VLLMRanker from haystack_integrations.components.generators.vllm import VLLMChatGenerator # 1) 索引文档嵌入 doc_store InMemoryDocumentStore() doc_embedder VLLMDocumentEmbedder(modelgoogle/embeddinggemma-300m) # 2) 查询文本嵌入 检索 重排 query_embedder VLLMTextEmbedder(modelgoogle/embeddinggemma-300m) retriever InMemoryEmbeddingRetriever(document_storedoc_store) ranker VLLMRanker(modelBAAI/bge-reranker-base) # 3) 生成基于检索结果的对话 generator VLLMChatGenerator( modelQwen/Qwen3-0.6B, generation_kwargs{max_tokens: 512}, )组件设计上遵循 Haystack 标准组件协议component装饰器、run/warm_up接口因此可以像使用任何内置组件一样通过Pipeline.add_component连接并通过Pipeline.from_dict/component.to_dict完成整条管道的序列化与恢复。需要高吞吐时可将run_async变体接入异步管道AsyncPipeline并行处理。几个落地建议模型与服务端配置一致性四个组件的model必须与vllm serve加载的模型一致否则请求会因模型不匹配而失败认证开关仅在服务端用--api-key启动时才需要显式设置api_key本地开发可直接依赖VLLM_API_KEY环境变量或默认无认证长文本处理嵌入与重排场景通过truncate_prompt_tokens控制输入截断Chat 场景通过max_tokens与stop控制输出远程部署将api_base_url改为远程 vLLM 服务的地址并通过http_client_kwargs注入代理、证书等传输层配置失败策略批量嵌入时默认raise_on_failureFalse会跳过失败文档并记录日志适合大语料灌库对结果敏感的场景可设为True及时暴露问题。七、小结vLLM 集成以 OpenAI 兼容协议为桥梁为 Haystack 提供了完整的自托管 LLM 能力矩阵嵌入侧VLLMDocumentEmbedder文档批量向量化支持batch_size、meta_fields_to_embed、Matryoshkadimensions裁剪与VLLMTextEmbedder查询向量化生成侧VLLMChatGenerator覆盖流式回调、工具调用、推理模型、结构化输出与运行时参数覆盖并支持to_dict/from_dict序列化排序侧VLLMRanker通过/rerank端点实现top_kscore_threshold双重过滤的精排。四个组件均通过extra_parameters或generation_kwargs[extra_body]透传 vLLM 私有参数且同步run与异步run_async双通道齐备可直接嵌入 Haystack 的同步/异步管道体系构建完全自托管的 RAG 与 Agent 应用。完整 API 定义见 vllm.md配套的数据结构与工具定义可在 chat_message.py、streaming_chunk.py 与 from_function.py 中进一步查阅。【免费下载链接】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），仅供参考