{{< 资源信息 >}} 您花了三天时间构建了一条漂亮的 Haystack 管道。 它将文档分块，嵌入它们，运行密集检索器，并将上下文传递给本地法学硕士。 它在您的 Jupyter 笔记本中完美运行。 然后你的产品经理问：“前端团队什么时候可以调用？” 你的心沉了下去。 您知道其中的痛苦：在 Flask 中包装管道、编写请求验证、生成 OpenAPI 模式、构建 Docker 映像、设置 CI/CD。 本应 30 分钟的任务变成了为期一周的工程冲刺。 这正是 Hayhooks 解决的问题。 Hayhooks 由 Deepset（15,000 多个明星 Haystack 框架背后的同一团队）构建，让您可以使用单个命令将任何 Haystack 管道部署为生产就绪的 REST API。 没有样板。 没有手写的 FastAPI 包装器。 无需 OpenAPI 架构维护。 在本指南中，我将向您展示如何在 10 分钟内从“pip install”转到已部署的容器，并使用实际大规模运行的生产强化模式。

## Hayhooks 是什么？ Hayhooks 是一个轻量级部署服务器，它将 Haystack NLP/LLM 管道公开为 REST API 端点。 将其视为管道代码和生产基础设施之间缺失的桥梁。 您编写管道，Hayhooks 处理 HTTP 层、请求验证、序列化、文档和部署打包。 该项目处于三个发展趋势的交叉点：定制 LLM 管道的爆炸式增长（截至 2026 年初，PyPI 上的 Haystack 下载量超过 420 万）、对自托管推理 API 的需求（由数据隐私要求驱动）以及对 API 优先 AI 架构的推动。 Hayhooks 由 deepset-ai 维护，在 Apache-2.0 下获得许可，并拥有大约 600 个 GitHub star 并每周发布活跃版本。 ## Hayhooks 的工作原理 Hayhooks 架构遵循一个简单但功能强大的模式：使用标准 Python API 定义 Haystack 管道，然后将其传递给 Hayhooks，Hayhooks 将其包装在 FastAPI 应用程序中。 以下是幕后发生的事情： 1. 管道摄取：Hayhooks 读取您的 Haystack“管道”对象 - 由检索器、嵌入器、生成器或自定义节点等组件构建。 2. 模式生成：使用从每个组件的“run()”方法签名派生的 Pydantic 模型，Hayhooks 自动生成请求/响应模式。 3. FastAPI 绑定：每个管道都成为一个 POST 端点。 端点名称源自管道或显式配置。 4. OpenAPI 文档：完全交互式的 Swagger UI 在“/docs”中提供，由架构自动生成。 5. 容器打包：内置的 Dockerfile 和 docker-compose 设置可让您打包生产所需的所有内容。 这里的关键见解是 Haystack 组件已经通过“@component”装饰器和“run()”方法签名声明了它们的输入和输出。 Hayhooks 利用此元数据创建类型安全的 HTTP API，无需任何额外配置。 ## 安装和设置 Hayhooks 在本地运行只需不到两分钟。 您需要 Python 3.9+ 和工作 pip 环境。 ### 第 1 步：安装 Hayhooks ```` bas h

创建虚拟环境 #

python -m venv hayhooks-env 源 hayhooks-env/bin/activate # Linux/Mac

hayhooks-env\Scripts\activate # Windows # 安装 Hayhooks 和 Haystack #

pip 安装 hayhooks haystack-ai 截至 2026 年 5 月，最新稳定版本是 **hayhooks v0.3.0** 和 **haystack-ai v2.12.0**。 验证您的安装： bas h python -c“导入hayhooks；打印（hayhooks.version）”

预期：0.3.0 #

### 步骤 2：定义一个简单的管道 创建一个名为“search_pipeline.py”的文件：蟒蛇 从干草堆导入管道 从 haystack.components.embedders 导入 SentenceTransformersTextEmbedder 从 haystack.components.retrievers 导入 InMemoryEmbeddingRetriever 从 haystack.document_stores.in_memory 导入 InMemoryDocumentStore 从 haystack.components.builders 导入 PromptBuilder 从 haystack.components.generators 导入 OpenAIGenerator # 构建文档存储 doc_store = InMemoryDocumentStore()

在生产中填充示例文档 模板=“”“ #

根据这些文件，回答问题。 文件： {% for 文档中的 doc %} {{ 文档.内容 }} {% 结束 %} 问题：{{问题}} 答： ”“” 管道 = 管道() pipeline.add_component(“嵌入器”, SentenceTransformersTextEmbedder()) pipeline.add_component(“retriever”, InMemoryEmbeddingRetriever(document_store=doc_store)) pipeline.add_component(“builder”, PromptBuilder(template=template)) pipeline.add_component(“生成器”, OpenAIGenerator(model=“gpt-4o-mini”)) pipeline.connect(“embedder.embedding”, “retriever.query_embedding”) pipeline.connect(“retriever.documents”, “builder.documents”) pipeline.connect(“builder.prompt”, “generator.prompt”) ### 步骤 3：使用 Hayhooks 进行部署 创建一个“deploy.py”文件：蟒蛇 从 hayhooks 导入 Hayhooks 从 search_pipeline 导入管道 应用程序 = Hayhooks() app.add_pipeline(“搜索”, 管道) 如果 name == “main”: 进口uvicorn uvicorn.run（应用程序，主机=“0.0.0.0”，端口= 8000） 启动服务器： bas h 蟒蛇部署.py 您将看到类似以下内容的输出： 信息：已启动服务器进程 [12345] 信息：等待应用程序启动。 信息：应用程序启动完成。 信息：Uvicorn 运行在 http://0.0.0.0:8000 ### 第 4 步：测试您的 API bas h

查看自动生成的文档 #

卷曲 http://localhost:8000/docs # 发送查询 卷曲 -X POST http://localhost:8000/search \ -H“内容类型：application/json”\ -d’{ “embedder”: {“text”: “什么是 Haystack？”}, “builder”: {“question”: “Haystack 是什么？”} }' 响应包括生成的答案和检索到的文档： ``` jso n { “发电机”：{ "replies": ["Haystack 是一个开源 NLP 框架..."] }, “猎犬”：{ “文件”：[...] } } 就是这样。 您的管道现在是一个生产 REST API，具有经过验证的 JSON 输入、类型化响应和交互式文档。 ## 与主流工具集成 Hayhooks 与周围的 MLOps 和 DevOps 生态系统完美集成。 以下是生产部署中最重要的集成。 ### Docker 部署 Hayhooks 附带了一个参考 Dockerfile。 创建一个“Dockerfile”： ``` dockerfil e 来自 python:3.11-slim 工作目录/应用程序 复制requirements.txt。 运行 pip install –no-cache-dir -rrequirements.txt 复制 search_pipeline.py deploy.py 。 曝光 8000 CMD [“python”，“deploy.py”] 还有一个“docker-compose.yml”： yam l 版本：‘3.8’ 服务： 干草钩： 建造： 。 端口： - “8000:8000” 环境： - OPENAI_API_KEY=${OPENAI_API_KEY} - HAYSTACK_LOG_LEVEL=信息 卷： - ./models:/app/models:ro 健康检查： 测试：[“CMD”，“curl”，“-f”，“http://localhost:8000/health”] 间隔：30秒 超时时间：10秒 重试次数：3 通过一个命令进行部署： bas h docker-compose up -d –build 对于生产 VPS 托管，我建议 DigitalOcean — 他们的应用程序平台通过零配置 SSL 和自动扩展来处理容器部署。 对于具有预配置 AI 运行时的托管容器堆栈，HTStack 提供一键式 Haystack 就绪环境。 ### OpenAI / Azure OpenAI 集成 使用云 LLM 提供商时，通过环境变量传递 API 密钥：蟒蛇 导入操作系统 从 haystack.components.generators 导入 OpenAIGenerator 生成器 = OpenAIGenerator( 型号=“gpt-4o”， api_key=os.getenv(“OPENAI_API_KEY”), api_base=os.getenv(“OPENAI_API_BASE”, “https://api.openai.com/v1") ） 对于 Azure OpenAI，将“api_base”设置为 Azure 端点并使用“azure_deployment”参数。 ### 自定义组件集成 Hayhooks 可与任何自定义 Haystack 组件配合使用。 以下是自定义预处理节点的示例：蟒蛇 从 hayhooks 导入 Hayhooks 从 haystack 导入组件 从输入导入列表 @组件 类 TextNormalizer： @component.output_types(标准化=str) def run(self, text: str) -> dict: 返回 {“标准化”：text.lower().strip()} 从干草堆导入管道 从 haystack.components.generators 导入 OpenAIGenerator 管道 = 管道() pipeline.add_component(“标准化器”, TextNormalizer()) pipeline.add_component(“生成器”, OpenAIGenerator()) pipeline.connect(“normalizer.normalized”, “generator.prompt”) 应用程序 = Hayhooks() app.add_pipeline（“normalize_generate”，管道） ### 使用 Prometheus 进行监控 添加 Prometheus 指标用于生产监控：蟒蛇 从 prometheus_client 导入计数器、直方图、make_asgi_app 从 hayhooks 导入 Hayhooks REQUEST_COUNT = Counter(‘hayhooks_requests_total’, ‘请求总数’, [‘管道’]) REQUEST_DURATION = Histogram(‘hayhooks_request_duration_seconds’, ‘请求持续时间’, [‘管道’]) 应用程序 = Hayhooks() 指标应用 = make_asgi_app() # 在 /metrics 处挂载指标 app.mount（“/指标”，metrics_app）

|