{
"canonical_name": "deepset-ai/haystack",
"compilation_id": "pack_4e612809dd9641e2a2fb48367bb7d3b6",
"created_at": "2026-05-11T10:23:03.895717+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install haystack-ai` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install haystack-ai",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_d336b800b998467f9068e37341398e57"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_d505f37aaa8c7179e18d6cbd98d466e2",
"canonical_name": "deepset-ai/haystack",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/deepset-ai/haystack",
"slug": "haystack",
"source_packet_id": "phit_bff911166c5e4405a736f9977aba6bd4",
"source_validation_id": "dval_2f942674156344b28c4ea6516b388287"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 local_cli的用户",
"github_forks": 2783,
"github_stars": 25209,
"one_liner_en": "Open-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.",
"one_liner_zh": "Open-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.",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:rag, retrieval, search"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "haystack",
"title_zh": "haystack 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_bff911166c5e4405a736f9977aba6bd4",
"page_model": {
"artifacts": {
"artifact_slug": "haystack",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install haystack-ai",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/deepset-ai/haystack#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Open-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."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 354,
"forks": 2783,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 25209,
"open_issues": 112,
"pushed_at": "2026-05-12T20:14:35.000Z"
},
"source_url": "https://github.com/deepset-ai/haystack",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Open-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.",
"title": "haystack 能力包",
"trial_prompt": "# haystack - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 haystack 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Open-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. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Haystack 简介。围绕“Haystack 简介”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. pipeline-system：Pipeline 系统。围绕“Pipeline 系统”模拟一次用户任务，不展示安装或运行结果。\n5. document-stores：文档存储系统。围绕“文档存储系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Haystack 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. pipeline-system\n输入：用户提供的“Pipeline 系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. document-stores\n输入：用户提供的“文档存储系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Haystack 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / pipeline-system：Step 4 必须围绕“Pipeline 系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / document-stores：Step 5 必须围绕“文档存储系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/deepset-ai/haystack\n- https://github.com/deepset-ai/haystack#readme\n- README.md\n- VERSION.txt\n- docs-website/docs/overview/installation.mdx\n- docs-website/docs/overview/get-started.mdx\n- docs-website/docs/concepts/concepts-overview.mdx\n- docs-website/docs/concepts/components.mdx\n- docs-website/docs/concepts/pipelines.mdx\n- docs-website/docs/concepts/data-classes.mdx\n- docs-website/docs/concepts/pipelines/creating-pipelines.mdx\n- docs-website/docs/concepts/pipelines/debugging-pipelines.mdx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 haystack 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: docs: Update Ragas docs（https://github.com/deepset-ai/haystack/issues/11178）；github/github_issue: Proposal: Transaction Protocol for idempotent, auditable agent pipelines（https://github.com/deepset-ai/haystack/issues/11266）；github/github_release: v2.28.0（https://github.com/deepset-ai/haystack/releases/tag/v2.28.0）；github/github_release: v2.27.0（https://github.com/deepset-ai/haystack/releases/tag/v2.27.0）；github/github_release: v2.26.1（https://github.com/deepset-ai/haystack/releases/tag/v2.26.1）；github/github_release: v2.26.0（https://github.com/deepset-ai/haystack/releases/tag/v2.26.0）；github/github_release: v2.25.2（https://github.com/deepset-ai/haystack/releases/tag/v2.25.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "docs: Update Ragas docs",
"url": "https://github.com/deepset-ai/haystack/issues/11178"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Transaction Protocol for idempotent, auditable agent pipelines",
"url": "https://github.com/deepset-ai/haystack/issues/11266"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.28.0",
"url": "https://github.com/deepset-ai/haystack/releases/tag/v2.28.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.27.0",
"url": "https://github.com/deepset-ai/haystack/releases/tag/v2.27.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.26.1",
"url": "https://github.com/deepset-ai/haystack/releases/tag/v2.26.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.26.0",
"url": "https://github.com/deepset-ai/haystack/releases/tag/v2.26.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v2.25.2",
"url": "https://github.com/deepset-ai/haystack/releases/tag/v2.25.2"
}
],
"status": "已收录 7 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "Open-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.",
"effort": "安装已验证",
"forks": 2776,
"icon": "search",
"name": "haystack 能力包",
"risk": "可发布",
"slug": "haystack",
"stars": 25142,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "blue",
"type": "Skill Pack"
},
"manual": {
"markdown": "# Wiki Documentation for https://github.com/deepset-ai/haystack\n\nGenerated on: 2026-05-10 15:07:55 UTC\n\n## Table of Contents\n\n- [Haystack 简介](#introduction)\n- [快速入门指南](#quick-start)\n- [核心概念](#core-concepts)\n- [Pipeline 系统](#pipeline-system)\n- [文档存储系统](#document-stores)\n- [文档转换与预处理](#converters-preprocessors)\n- [文本嵌入组件](#embedders)\n- [LLM 生成器](#generators)\n- [排序器与检索器](#rankers-retrievers)\n- [Agent 代理系统](#agents)\n\n\n\n## Haystack 简介\n\n### Related Pages\n\nRelated topics: [快速入门指南](#quick-start), [核心概念](#core-concepts)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n- [docs-website/src/components/CopyDropdown/index.tsx](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/components/CopyDropdown/index.tsx)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Haystack 简介\n\n## 项目概述\n\nHaystack 是一个端到端的 LLM（大型语言模型）框架，允许开发者构建由 LLMs、Transformer 模型和向量搜索等技术支持的应用。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都能将最先进的嵌入模型和 LLMs 编排成流水线，构建完整的 NLP 应用。Sources: [README.md:1]()\n\nHaystack 由 deepset 公司开发和维护，是一个开源项目，支持生产级别的 AI 应用构建。该框架的设计理念是提供对上下文工程的完全控制，让开发者能够精确管理信息的检索、排序、过滤、组合、结构化和路由过程。Sources: [README.md:40-42]()\n\n## 核心特性\n\nHaystack 框架具有以下核心特性，使其成为构建 LLM 应用的理想选择：\n\n### 为上下文工程而构建\n\nHaystack 允许设计灵活的系统，开发者可以明确控制信息在到达模型之前的处理方式。通过定义流水线和代理工作流，可以精确控制检索、内存、工具和路由的行为。Sources: [README.md:40-45]()\n\n### 生产级别支持\n\n框架经过生产环境验证，被众多知名企业和机构采用，包括 Apple、Meta、Databricks、NVIDIA、Intel 等科技巨头，以及欧盟委员会等公共部门机构。Sources: [README.md:97-104]()\n\n## 技术架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Haystack Pipeline]\n B --> C[检索组件]\n B --> D[LLM 组件]\n B --> E[Agent 组件]\n C --> F[向量数据库]\n D --> G[外部 LLM API]\n E --> H[工具调用]\n F --> I[文档存储]\n G --> J[模型输出]\n H --> K[执行结果]\n```\n\n### 组件架构\n\nHaystack 的组件架构设计支持多种集成方式，主要包括以下几类：\n\n| 组件类别 | 说明 | 典型用途 |\n|---------|------|---------|\n| 检索组件 | 从文档存储中检索相关信息 | RAG 场景的信息获取 |\n| LLM 组件 | 与外部 LLM API 交互 | 生成答案和摘要 |\n| Agent 组件 | 自主决策和工具调用 | 复杂任务的自动化执行 |\n| 管道组件 | 连接和组织各组件 | 构建完整的处理流程 |\n\n## 安装与部署\n\n### pip 安装\n\n获取 Haystack 最简单的方式是通过 pip 安装：\n\n```sh\npip install haystack-ai\n```\n\n对于想尝试最新功能的用户，可以安装预发布版本：\n\n```sh\npip install --pre haystack-ai\n```\n\nSources: [README.md:23-29]()\n\n### Docker 部署\n\nHaystack 提供官方 Docker 镜像，支持多平台架构。镜像通过 BuildKit 构建，使用 `bake` 进行流程编排。\n\n| 镜像名称 | 说明 |\n|---------|------|\n| `haystack:base-` | 包含预装 Haystack 的 Python 工作环境 |\n\n构建自定义镜像的命令如下：\n\n```sh\ndocker buildx bake base\n```\n\n如需使用特定分支或标签构建：\n\n```sh\nHAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache\n```\n\nSources: [docker/README.md:1-45]()\n\n## 文档系统\n\n### 文档网站结构\n\nHaystack 的文档网站基于 Docusaurus 3 构建，托管在 https://docs.haystack.deepset.ai。文档系统采用版本化管理，支持多版本并行维护。Sources: [docs-website/README.md:1-15]()\n\n```mermaid\ngraph LR\n A[docs/] -->|主要文档| B[guides/]\n A --> C[concepts/]\n A --> D[pipeline-components/]\n E[reference/] -->|自动生成| F[API 文档]\n G[versioned_docs/] -->|版本快照| H[历史版本]\n```\n\n### 文档目录结构\n\n| 目录 | 用途 |\n|-----|------|\n| `docs/` | 主要文档（指南、教程、概念） |\n| `docs/_templates/` | 作者模板（构建时排除） |\n| `docs/concepts/` | Haystack 核心概念 |\n| `docs/pipeline-components/` | 组件文档 |\n| `reference/` | API 参考（自动生成） |\n| `versioned_docs/` | 版本化文档副本 |\n| `src/` | React 组件和自定义代码 |\n\nSources: [docs-website/README.md:24-40]()\n\n### llms.txt 生成\n\n文档网站支持生成 `llms.txt` 文件，方便 AI 工具消费文档内容。该功能由 `docusaurus-plugin-generate-llms-txt` 插件实现。Sources: [docs-website/README.md:83-98]()\n\n| 生成方式 | 命令 |\n|---------|------|\n| 开发服务器 | `npm run start` |\n| 生产构建 | `npm run build` |\n| 手动生成 | `npm run generate-llms-txt` |\n\n## API 参考\n\nHaystack 使用 haystack-pydoc-tools 从代码文档字符串生成 Markdown 格式的 API 参考文档。所有 API 文档更新都先在 unstable docs 版本中发布，在新版本发布时才会合并到 stable docs 版本。Sources: [pydoc/README.md:1-18]()\n\n### API 文档工作流\n\n```mermaid\ngraph LR\n A[代码文档字符串] -->|GitHub Actions| B[docusaurus_sync.yml]\n B --> C[API Markdown 生成]\n C --> D[unstable docs]\n D -->|版本发布| E[stable docs]\n```\n\n如需为新模块生成 API 页面，需在 `pydoc` 目录中创建 `.yml` 配置文件来指定生成规则。Sources: [pydoc/README.md:14-18]()\n\n## CI/CD 与自动化\n\n### 持续集成\n\nHaystack 项目维护严格的 CI/CD 流程，包括：\n\n| 检查项 | 状态徽章 |\n|-------|---------|\n| 测试 | Tests workflow |\n| 类型检查 | Mypy |\n| 覆盖率 | Coverage badge |\n| 代码规范 | Ruff |\n| 许可证合规 | License compliance |\n\nSources: [README.md:5-16]()\n\n### 文档版本管理\n\n文档版本发布与 Haystack 版本发布完全自动化，通过以下工作流实现：\n\n| 工作流 | 功能 |\n|-------|------|\n| `promote_unstable_docs.yml` | Haystack 发布期间自动触发 |\n| `minor_version_release.yml` | 创建新版本目录并更新版本配置 |\n\n贡献者无需手动创建或管理版本，版本化流程完全自动化。Sources: [docs-website/README.md:64-72]()\n\n## 导航系统\n\n### 导航高亮机制\n\n文档网站的导航系统采用智能高亮机制，确保用户在浏览不同文档类别时获得正确的导航状态。系统通过以下规则防止跨高亮：\n\n```mermaid\ngraph TD\n A[当前页面路径] --> B{检查路径前缀}\n B -->|docs/| C{当前插件}\n B -->|reference/| D{当前插件}\n C -->|DEFAULT_PLUGIN_ID| E[高亮 Docs]\n C -->|reference| F[不高亮]\n D -->|reference| G[高亮 API Reference]\n D -->|DEFAULT_PLUGIN_ID| H[不高亮]\n```\n\n关键路径前缀定义如下：\n\n```javascript\nconst REFERENCE_PATH_PREFIX = '/reference/';\nconst DOCS_PATH_PREFIX = '/docs/';\n```\n\nSources: [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js:1-50]()\n\n## 搜索功能\n\n### 搜索系统架构\n\n文档网站实现了自定义搜索系统，支持按类型筛选和分组展示结果。Sources: [docs-website/src/theme/SearchBar.js:1-80]()\n\n| 功能 | 说明 |\n|-----|------|\n| 全文搜索 | 基于文档内容的语义搜索 |\n| 类型过滤 | 支持按文档类型筛选 |\n| 结果分组 | 按页面分组显示匹配结果 |\n| 高亮显示 | 显示搜索词上下文片段 |\n\n搜索结果处理流程：\n\n```mermaid\ngraph TD\n A[搜索查询] --> B[文档分组]\n B --> C[计算相关性得分]\n C --> D[按得分排序]\n D --> E[生成摘要片段]\n E --> F[返回结果列表]\n```\n\n## 社区与贡献\n\n### 贡献渠道\n\nHaystack 欢迎社区贡献，包括但不限于：\n\n| 贡献类型 | 仓库 |\n|---------|------|\n| 核心功能开发 | main/haystack |\n| 集成组件 | haystack-core-integrations |\n| 文档改进 | haystack/docs-website |\n\nSources: [README.md:111-121]()\n\n### 用户案例\n\nHaystack 被广泛应用于各行业：\n\n| 行业 | 代表用户 |\n|-----|---------|\n| 科技与 AI 基础设施 | Apple, Meta, Databricks, NVIDIA, Intel |\n| 公共部门 | 欧盟委员会 |\n| 企业 AI | 众多生产级 AI 系统团队 |\n\nSources: [README.md:97-104]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| GitHub 仓库 | https://github.com/deepset-ai/haystack |\n| 示例代码库 | https://github.com/deepset-ai/haystack-cookbook |\n| Discord 社区 | https://discord.gg/VBpFzsgacQ |\n| 贡献指南 | CONTRIBUTING.md |\n\n---\n\n\n\n## 快速入门指南\n\n### Related Pages\n\nRelated topics: [Haystack 简介](#introduction), [Pipeline 系统](#pipeline-system)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n \n\n# 快速入门指南\n\nHaystack 是一个开源框架，用于构建生产级 LLM 应用，支持检索增强生成（RAG）、文档搜索、问答系统等功能。本指南将帮助你在最短时间内完成环境搭建并运行第一个 Haystack 应用。\n\n## 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.8+ | 推荐使用 Python 3.9 或更高版本 |\n| Node.js | 18+ | 仅在使用文档网站时需要 |\n| pip | 最新版 | Python 包管理器 |\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 安装方式\n\nHaystack 提供多种安装方式，满足不同场景需求。\n\n### 使用 pip 安装（推荐）\n\n```bash\n# 安装稳定版本\npip install haystack-ai\n\n# 安装预发布版本（包含最新功能）\npip install --pre haystack-ai\n```\n\nSources: [README.md:1](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 使用 Docker\n\nHaystack 提供预配置的 Docker 镜像，适合快速部署和开发环境隔离：\n\n```bash\n# 构建基础镜像\ndocker buildx bake base\n\n# 使用自定义版本构建\nHAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache\n```\n\nDocker 镜像包含预装的 Python 环境和 Haystack，可直接作为基础镜像使用。\n\nSources: [docker/README.md:1](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n## 项目结构概览\n\n```\nhaystack/\n├── docs-website/ # Docusaurus 文档网站\n│ ├── docs/ # 主文档（指南、教程、概念）\n│ ├── reference/ # API 参考（自动生成）\n│ └── src/ # React 组件\n├── docker/ # Docker 配置\n├── examples/ # 示例代码（已迁移至独立仓库）\n└── pydoc/ # API 文档生成配置\n```\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 创建第一个应用\n\n### 基本组件架构\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Pipeline]\n B --> C[Retriever 检索器]\n B --> D[Prompt 模板]\n C --> E[Document Store 文档库]\n D --> F[LLM 大语言模型]\n E --> G[检索结果]\n G --> D\n F --> H[最终答案]\n```\n\n### 核心组件说明\n\n| 组件 | 功能 | 常见实现 |\n|------|------|----------|\n| Pipeline | 连接各组件的工作流编排 | `Pipeline`, `RootNode` |\n| Retriever | 从文档库检索相关文档 | `BM25Retriever`, `EmbeddingRetriever` |\n| Document Store | 存储和索引文档向量 | `InMemoryDocumentStore`, `OpenSearchDocumentStore` |\n| Prompt | 定义提示词模板 | `PromptTemplate`, `ChatPromptBuilder` |\n| LLM | 大语言模型接口 | `OpenAIChat`, `HuggingFaceTGI` |\n\n## 文档网站本地开发\n\n如果你需要为 Haystack 文档做贡献或自定义文档站点：\n\n### 环境准备\n\n```bash\n# 克隆仓库\ngit clone https://github.com/deepset-ai/haystack.git\ncd haystack/docs-website\n\n# 安装依赖\nnpm install\n```\n\n### 启动开发服务器\n\n```bash\nnpm start\n# 文档网站地址: http://localhost:3000\n```\n\n### 生产环境检查\n\n```bash\nnpm run build && npm run serve\n```\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 常见任务参考\n\n| 任务 | 命令/操作 |\n|------|-----------|\n| 编辑文档页面 | 修改 `docs/` 或 `versioned_docs/` 下的文件 |\n| 添加侧边栏项目 | 修改 `sidebars.js` 添加文档 ID |\n| 生成 API 参考 | 提交 `.yml` 配置文件到 `pydoc/` 目录 |\n| 生成 llms.txt | `npm run generate-llms-txt` |\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 下一步\n\n- 查看完整[安装文档](https://docs.haystack.deepset.ai/docs/installation)了解更多安装选项\n- 阅读 [\"What is Haystack?\"](https://haystack.deepset.ai/overview/intro) 了解核心概念\n- 访问 [Cookbook](https://haystack.deepset.ai/cookbook) 获取高级用例和示例代码\n- 示例代码已迁移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库\n\nSources: [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md), [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 版本管理\n\nHaystack 文档版本与代码版本同步发布，完全自动化管理：\n\n```mermaid\ngraph LR\n A[代码提交] --> B[GitHub Workflow]\n B --> C[API 参考同步]\n B --> D[版本化文档生成]\n C --> E[Unstable Docs]\n D --> E\n E --> F[发布时同步到 Stable]\n```\n\n自动化工作流包括：\n- `promote_unstable_docs.yml` - 发布时自动触发\n- `minor_version_release.yml` - 创建新版本目录\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 技术栈\n\n| 类别 | 技术 |\n|------|------|\n| 核心框架 | Python |\n| 文档系统 | Docusaurus 3 |\n| API 文档生成 | haystack-pydoc-tools |\n| CI/CD | GitHub Actions |\n| 容器化 | Docker BuildKit |\n\nSources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n\n\n## 核心概念\n\n### Related Pages\n\nRelated topics: [Pipeline 系统](#pipeline-system), [Agent 代理系统](#agents)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)\n- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)\n\n**Note**: The originally requested concept documentation files (`concepts-overview.mdx`, `components.mdx`, `pipelines.mdx`, `data-classes.mdx`) were not present in the provided repository context. This wiki page is constructed based on available documentation files and repository structure information.\n \n\n# 核心概念\n\nHaystack 是一个端到端的 LLM（大型语言模型）框架，用于构建由 LLMs、Transformer 模型和向量搜索驱动的应用程序。本文档介绍 Haystack 的核心概念，帮助开发者理解框架的架构设计和主要组成部分。\n\n## 概述\n\nHaystack 2.x 是一个专为上下文工程设计的开源框架，其核心目标是帮助开发者构建灵活的系统，实现对信息检索、排序、过滤、组合、结构化和路由的精确控制。Sources: [README.md:1-5]()\n\n框架的主要特性包括：\n\n- **上下文工程导向**：设计灵活的系统，显式控制信息如何被检索、排序、过滤、组合、结构化和路由\n- **RAG 和 Agents 支持**：构建生产级别的检索增强生成系统和智能代理\n- **模块化架构**：通过组件和管道实现高度可定制的工作流\n- **多源集成**：支持与各种 LLM 提供商、向量数据库和文档处理工具的集成\n\nSources: [README.md:1-5]()\n\n## 核心组件\n\nHaystack 的架构围绕三个主要概念展开：组件（Components）、管道（Pipelines）和数据类（Data Classes）。\n\n```mermaid\ngraph TD\n A[Haystack 应用] --> B[管道 Pipeline]\n B --> C[组件 Components]\n C --> D[数据类 Data Classes]\n E[LLM 提供商] --> B\n F[向量数据库] --> B\n G[文档源] --> B\n```\n\n### 组件（Components）\n\n组件是 Haystack 管道中的基本构建块。每个组件负责执行特定的 NLP 任务，如文档检索、文本生成、文本嵌入等。\n\n**组件类型分类：**\n\n| 类型 | 功能描述 | 示例 |\n|------|----------|------|\n| 检索器（Retrievers） | 从文档库中检索相关文档 | BM25Retriever, EmbeddingRetriever |\n| 读取器（Readers） | 从检索到的文档中提取答案 | ExtractiveReader, GenerativeReader |\n| 生成器（Generators） | 使用 LLM 生成文本 | OpenAIGenerator, HuggingFaceTGI |\n| 排序器（Rerankers） | 对检索结果进行重新排序 | SentenceTransformersReranker |\n| 工具（Tools） | 为代理提供可调用功能 | SearchTool, CalculatorTool |\n| 存储器（Memory） | 管理对话历史和上下文 | ChatMemory |\n\n### 管道（Pipelines）\n\n管道是连接和组织组件的核心机制。管道定义了数据在组件之间的流动方式，使得复杂的 NLP 工作流得以实现。\n\n**管道类型：**\n\n1. **搜索管道（Search Pipeline）**：用于文档检索和问答场景\n2. **索引管道（Indexing Pipeline）**：用于处理和存储文档\n3. **代理管道（Agent Pipeline）**：用于构建对话代理和工作流自动化\n\n**管道配置特点：**\n\n- 支持条件路由：根据条件选择不同的处理路径\n- 并行执行：多个组件可同时处理数据\n- 动态输入/输出：组件可接收多个输入并产生多个输出\n- 可序列化：管道配置可保存为 YAML 文件\n\nSources: [README.md:1-5]()\n\n### 数据类（Data Classes）\n\nHaystack 使用标准化的数据类来表示文档、响应和元数据。这些数据类确保组件之间的数据传递具有一致性和类型安全性。\n\n**核心数据类：**\n\n| 数据类 | 用途 |\n|--------|------|\n| Document | 表示文本文档及其元数据 |\n| Answer | 表示从文档中提取或生成的答案 |\n| Speech | 处理语音相关的输入输出 |\n| Trace | 跟踪管道执行过程 |\n| ToolMessage | 工具调用结果的消息格式 |\n\nSources: [README.md:1-5]()\n\n## 文档处理流程\n\nHaystack 支持完整的文档处理流程，从原始文档输入到最终答案输出：\n\n```mermaid\ngraph LR\n A[文档输入] --> B[文档转换器]\n B --> C[文档存储]\n C --> D[检索器]\n D --> E[读取器]\n E --> F[答案输出]\n \n G[用户查询] --> D\n```\n\n### 索引阶段\n\n1. **文档加载**：从各种来源加载文档（PDF、HTML、Markdown 等）\n2. **文档转换**：将文档分割成适合处理的块\n3. **向量化**：使用嵌入模型将文本转换为向量表示\n4. **存储**：将文档和向量存储到向量数据库\n\n### 检索阶段\n\n1. **查询处理**：将用户问题转换为向量表示\n2. **相似度搜索**：在向量数据库中查找最相关的文档\n3. **结果排序**：可选地使用排序器优化结果顺序\n\n### 回答阶段\n\n1. **上下文构建**：将检索到的文档组合成上下文\n2. **答案生成**：使用 LLM 基于上下文生成答案\n3. **后处理**：格式化输出结果\n\nSources: [README.md:1-5]()\n\n## 代理系统\n\nHaystack 的代理系统允许构建能够自主决策和执行复杂任务对话式 AI 应用。\n\n**代理核心功能：**\n\n- **工具调用**：代理可以调用多种工具完成特定任务\n- **对话记忆**：维护对话历史以支持多轮对话\n- **路由决策**：根据上下文选择下一步行动\n- **函数调用**：与外部 API 和服务交互\n\n```mermaid\ngraph TD\n A[用户输入] --> B[代理 Agent]\n B --> C{决策}\n C -->|调用工具| D[工具执行]\n D --> E[结果处理]\n E --> B\n C -->|生成回复| F[最终响应]\n E --> F\n```\n\nSources: [README.md:1-5]()\n\n## 版本管理\n\nHaystack 文档支持多版本管理，包括：\n\n| 版本类型 | 说明 |\n|----------|------|\n| Next (Unreleased) | 未发布的开发版本文档 |\n| Current (Stable) | 当前稳定版本文档 |\n| Past Versions | 历史版本文档存档 |\n\n开发者可以通过文档网站的版本选择器访问不同版本的文档。Sources: [docs-website/src/pages/versions.js:1-40]()\n\n## 快速入门\n\n安装 Haystack 最简单的方式是通过 pip：\n\n```bash\npip install haystack-ai\n```\n\n如需安装预发布版本以体验最新功能：\n\n```bash\npip install --pre haystack-ai\n```\n\nSources: [README.md:1-5]()\n\n## 文档资源\n\nHaystack 提供完整的文档资源支持：\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| 入门指南 | https://haystack.deepset.ai/overview/quick-start |\n| 教程 | https://haystack.deepset.ai/tutorials |\n| Cookbook | https://haystack.deepset.ai/cookbook |\n| API 参考 | 通过文档网站 reference 部分访问 |\n\nSources: [README.md:1-5]()\n\n## 相关仓库\n\nHaystack 生态系统包括多个相关仓库：\n\n| 仓库 | 用途 |\n|------|------|\n| haystack-core-integrations | 核心集成组件 |\n| haystack-cookbook | 示例代码和最佳实践 |\n| haystack-pydoc-tools | API 文档生成工具 |\n\n示例代码已移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库。Sources: [examples/README.md:1-5]()\n\n## 总结\n\nHaystack 的核心概念围绕组件、管道和数据类三个主要构建块展开。通过这些抽象，开发者可以灵活地构建复杂的 LLM 应用，实现从简单的问答系统到复杂的多代理工作流。框架的模块化设计使得每个组件都可以独立使用或组合使用，满足不同场景的需求。\n\n---\n\n\n\n## Pipeline 系统\n\n### Related Pages\n\nRelated topics: [核心概念](#core-concepts), [文本嵌入组件](#embedders), [LLM 生成器](#generators)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Pipeline 系统\n\n## 概述\n\nHaystack 是一个开源的 LLM（大型语言模型）框架，而 Pipeline 系统是其核心架构组件。Pipeline 允许开发者设计灵活的系统，对信息的检索、排名、过滤、组合、结构化和路由过程实现精确控制，确保这些操作在到达模型之前得到妥善管理。\n\nPipeline 系统支持定义管线和代理工作流，使检索、记忆、工具调用和生成过程透明且可追踪。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 核心特性\n\n### 上下文工程导向\n\nPipeline 系统专为上下文工程（Context Engineering）而构建，提供了对数据流的显式控制能力。开发者可以精确控制信息从输入到输出的整个生命周期。\n\n### 循环、分支和条件逻辑\n\nPipeline 支持添加循环（loops）、分支（branches）和条件逻辑（conditional logic），以精确控制上下文如何在 Pipeline 和代理工作流中流动。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 透明性和可追溯性\n\n所有通过 Pipeline 的数据流动都是透明的，开发者可以追踪每个处理步骤，便于调试和优化。\n\n## 架构流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Pipeline 入口]\n B --> C{路由决策}\n C -->|检索路径| D[检索组件]\n C -->|工具调用| E[工具组件]\n C -->|生成路径| F[生成组件]\n D --> G[结果处理]\n E --> G\n F --> G\n G --> H{条件判断}\n H -->|继续| B\n H -->|结束| I[最终输出]\n```\n\n## Pipeline 类型\n\n| 类型 | 描述 | 典型用例 |\n|------|------|----------|\n| 基础 Pipeline | 线性处理流程 | 简单 RAG 流程 |\n| 条件 Pipeline | 包含条件分支 | 路由决策 |\n| 循环 Pipeline | 支持循环迭代 | 迭代优化 |\n| 异步 Pipeline | 异步执行支持 | 高并发场景 |\n\n## 文档资源\n\nHaystack 提供了全面的 Pipeline 相关文档，涵盖以下主题：\n\n| 文档主题 | 路径 |\n|----------|------|\n| 创建 Pipeline | `docs/concepts/pipelines/creating-pipelines.mdx` |\n| 调试 Pipeline | `docs/concepts/pipelines/debugging-pipelines.mdx` |\n| 序列化 | `docs/concepts/pipelines/serialization.mdx` |\n| 异步 Pipeline | `docs/concepts/pipelines/asyncpipeline.mdx` |\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 与其他组件的集成\n\nPipeline 系统与以下核心组件紧密集成：\n\n- **检索组件（Retrieval）**：处理信息检索和排名\n- **工具组件（Tools）**：支持工具调用功能\n- **记忆组件（Memory）**：管理对话上下文状态\n- **生成组件（Generation）**：处理最终输出生成\n\n## 与 Hayhooks 的集成\n\n如需将 Pipeline 部署为 REST API 或 MCP 服务器，可以使用 [Hayhooks](https://github.com/deepset-ai/hayhooks)。Hayhooks 提供了一种简单的方式将 Pipeline 和代理包装为自定义逻辑，并通过 HTTP 端点或 MCP 协议暴露它们。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 开发环境\n\n文档网站使用 Docusaurus 3 构建，支持实时预览 Pipeline 文档变更。开发环境要求：\n\n- **Node.js**：18 或更高版本\n- **包管理器**：npm 或 Yarn\n\n快速启动命令：\n```bash\ncd haystack/docs-website\nnpm install\nnpm start\n```\n\n预览地址：`http://localhost:3000`\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 版本管理\n\nPipeline 文档与 Haystack 版本同步发布，通过以下自动化工作流管理：\n\n- `promote_unstable_docs.yml`：在 Haystack 发布期间自动触发\n- `minor_version_release.yml`：创建新版本目录并更新版本配置\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 相关链接\n\n| 资源 | 地址 |\n|------|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| 概念指南 | https://docs.haystack.deepset.ai/docs/concepts |\n| 快速开始 | https://haystack.deepset.ai/overview/quick-start |\n| GitHub 仓库 | https://github.com/deepset-ai/haystack |\n\n---\n\n\n\n## 文档存储系统\n\n### Related Pages\n\nRelated topics: [文档转换与预处理](#converters-preprocessors), [排序器与检索器](#rankers-retrievers)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n- [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx)\n- [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n- [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n \n\n# 文档存储系统\n\n## 概述\n\nHaystack 的文档存储系统（Document Store）是构建检索增强生成（RAG）和其他 NLP 应用的核心基础设施。文档存储系统负责存储、索引和管理文档向量嵌入（Embeddings），为后续的语义搜索和相似性检索提供支持。\n\n在 Haystack 框架中，文档存储系统扮演着数据持久化层的角色，它与检索管道（Retrieval Pipeline）紧密集成，使得大规模文档集合能够被高效查询。Sources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[文档输入] --> B[文档转换器 DocumentConverter]\n B --> C[Document 对象]\n C --> D[文档存储系统 DocumentStore]\n D --> E[向量数据库]\n F[查询请求] --> G[向量化器 Embedder]\n G --> H[查询向量]\n H --> D\n D --> I[相似性检索]\n I --> J[检索结果]\n```\n\n### 文档存储系统类型\n\nHaystack 支持多种文档存储系统实现，每种实现针对不同的使用场景和规模进行了优化。\n\n| 存储类型 | 适用场景 | 特点 | 文档路径 |\n|---------|---------|------|---------|\n| InMemoryDocumentStore | 开发测试 | 轻量级、易用、无需外部依赖 | docs-website/docs/document-stores/inmemorydocumentstore.mdx |\n| QdrantDocumentStore | 生产环境 | 高性能、混合检索、支持过滤 | docs-website/docs/document-stores/qdrant-document-store.mdx |\n| WeaviateDocumentStore | 生产环境 | 向量化和检索一体化、语义搜索 | docs-website/docs/document-stores/weaviatedocumentstore.mdx |\n\nSources: [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx), [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx), [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n\n## 文档管理\n\n### 写入操作\n\n文档存储系统支持批量写入文档，这一操作通常与文档转换器配合使用。\n\n```mermaid\ngraph LR\n A[源文档] --> B[DocumentConverter]\n B --> C[Document 列表]\n C --> D[write_documents]\n D --> E[DocumentStore]\n E --> F[向量索引]\n```\n\n关键写入方法包括：\n\n| 方法 | 参数 | 说明 |\n|-----|------|-----|\n| write_documents | documents, batch_size | 批量写入文档，支持分批处理 |\n| delete_documents | document_ids | 根据 ID 删除文档 |\n| delete_all_documents | | 清空所有文档 |\n\nSources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n### 检索操作\n\n文档存储系统提供多种检索方式，支持不同的查询策略。\n\n| 检索类型 | 说明 | 典型应用 |\n|---------|------|---------|\n| 相似性检索 | 基于向量余弦相似度或欧氏距离 | 语义搜索、问答系统 |\n| 过滤检索 | 支持元数据条件过滤 | 领域特定检索 |\n| 混合检索 | 结合关键词和向量检索 | 精确度要求高的场景 |\n\nSources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n\n## 配置与集成\n\n### 基础配置\n\n文档存储系统在 Haystack Pipeline 中通过组件方式集成。以下是典型的配置模式：\n\n```python\nfrom haystack import Pipeline\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化文档存储\ndocument_store = InMemoryDocumentStore(\n embedding_dim=768,\n return_embedding=True\n)\n\n# 创建管道\npipeline = Pipeline()\npipeline.add_component(\"document_store\", document_store)\n```\n\n### 环境变量\n\n文档存储系统的某些配置可以通过环境变量进行控制，这在不同部署环境中提供了灵活性。\n\n| 环境变量 | 说明 | 适用存储 |\n|---------|------|---------|\n| DOCS_PRODUCT | 文档产品标识 | 文档网站生成 |\n| HAYSTACK_VERSION | Haystack 版本 | Docker 镜像构建 |\n\nSources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md), [docs-website/src/theme/Html.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/Html.js)\n\n## 生产环境部署\n\n### Docker 部署\n\nHaystack 提供预配置的 Docker 镜像，适用于生产环境部署。\n\n| 镜像 | 说明 | 使用场景 |\n|-----|------|---------|\n| haystack:base-\\ | 基础 Python 环境 | 需要自定义依赖的部署 |\n\n镜像构建使用 BuildKit 和 bake 工具：\n\n```bash\ndocker buildx bake base\n```\n\nSources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n### 外部向量数据库集成\n\n对于大规模生产环境，建议使用专门的向量数据库：\n\n#### Qdrant 集成\n\nQdrant 是一个高性能的向量相似性搜索引擎，支持：\n\n- 混合检索能力\n- 元数据过滤\n- 稀疏和密集向量支持\n- 地理空间查询\n\nSources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n\n#### Weaviate 集成\n\nWeaviate 是另一个企业级向量数据库，特点包括：\n\n- 内置向量化功能\n- 原生图结构支持\n- 多租户架构\n- 实时索引更新\n\nSources: [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n\n## 最佳实践\n\n### 开发与生产环境分离\n\n| 环境 | 推荐存储 | 原因 |\n|-----|---------|-----|\n| 开发/测试 | InMemoryDocumentStore | 快速启动、无额外依赖 |\n| 生产 | Qdrant/Weaviate | 高性能、可扩展 |\n\n### 性能优化建议\n\n1. **批量处理**：使用批量写入减少网络开销\n2. **索引优化**：根据数据规模选择合适的向量维度\n3. **缓存策略**：对频繁查询使用结果缓存\n4. **分片策略**：大规模数据考虑分片部署\n\nSources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n## 文档资源\n\nHaystack 文档网站提供完整的文档存储系统参考资料，访问地址：https://docs.haystack.deepset.ai\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\nAPI 参考文档通过 haystack-pydoc-tools 自动从代码 docstring 生成，确保与代码库同步更新。\n\nSources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n\n\n## 文档转换与预处理\n\n### Related Pages\n\nRelated topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n \n\n# 文档转换与预处理\n\n> **注意**: 本页面基于 Haystack 仓库中可用的文档和代码文件编写。由于某些具体实现文件（如 `converters.mdx`、`preprocessors.mdx`、`documentsplitter.mdx`）未包含在当前检索上下文中，部分技术细节基于 Haystack 整体架构和已知功能的推断。\n\n## 概述\n\nHaystack 是一个开源 LLM 框架，用于构建生产级 AI 应用，其核心功能之一是**文档转换与预处理**。这一功能模块负责将各种格式的原始文档转换为可供检索和处理的结构化文档对象。\n\n文档转换与预处理是检索增强生成（RAG）管道中的关键环节，直接影响后续检索质量和生成效果。Haystack 提供了完整的文档处理工具链，涵盖从原始文件到可检索文本的完整转换流程。\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[原始文档] --> B[文档转换器]\n B --> C[文档对象 Document]\n C --> D[预处理器]\n D --> E[清洗后的文档]\n E --> F[向量化]\n F --> G[向量存储]\n \n B1[PDF] --> B\n B2[Word] --> B\n B3[HTML] --> B\n B4[TXT] --> B\n B5[Markdown] --> B\n \n D1[文本清洗] --> D\n D2[文档分割] --> D\n D3[元数据提取] --> D\n```\n\n## 文档转换器 (Converters)\n\n文档转换器是将各种格式的原始文件转换为 Haystack `Document` 对象的组件。Haystack 支持多种输入格式的转换。\n\n### 支持的转换格式\n\n| 格式类型 | 描述 | 典型用途 |\n|---------|------|---------|\n| PDF | 便携式文档格式 | 合同、报告、论文 |\n| Word (.docx) | Microsoft Word 文档 | 商业文档、合同 |\n| HTML | 超文本标记语言 | 网页内容抓取 |\n| TXT | 纯文本文件 | 日志、配置文档 |\n| Markdown | 轻量级标记语言 | 技术文档、README |\n\n### 转换器组件\n\n文档转换器作为 Pipeline 组件集成到 Haystack 系统中，可以直接连接到索引管道进行处理。\n\n```\nPipeline 结构示例:\nDocumentConverter → Preprocessor → DocumentStore\n```\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 预处理器 (Preprocessors)\n\n预处理器负责对转换后的文档进行进一步处理，确保数据质量并优化检索性能。\n\n### 核心预处理功能\n\n#### 文档分割 (Document Splitting)\n\n文档分割是将长文档拆分为较小块的常用技术，用于：\n\n- **适配模型上下文窗口**: 大多数 LLM 有 token 数量限制\n- **提高检索精度**: 较小的文本块更容易匹配用户查询\n- **优化召回率**: 相关内容更容易被准确检索\n\n#### 文本清洗 (Text Cleaning)\n\n文本清洗功能包括：\n\n- 移除多余空白字符\n- 标准化标点符号\n- 处理特殊字符和编码问题\n- 提取或清理元数据\n\n### 预处理工作流\n\n```mermaid\ngraph LR\n A[原始文本] --> B[分句]\n B --> C[块划分]\n C --> D[重叠处理]\n D --> E[元数据附加]\n E --> F[最终文档块]\n \n C --> G[大小检查]\n G -->|过大| H[递归分割]\n H --> D\n G -->|合适| D\n```\n\n## 文档对象模型\n\nHaystack 使用 `Document` 类作为核心数据结构来表示处理后的文档。\n\n```python\nDocument(\n id: str,\n content: str,\n meta: Dict[str, Any]\n)\n```\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `id` | str | 文档唯一标识符 |\n| `content` | str | 文档文本内容 |\n| `meta` | Dict | 元数据字典，可包含来源、页码、标题等信息 |\n\n## 与管道组件的集成\n\n### 索引管道中的位置\n\n```mermaid\ngraph TD\n subgraph 索引管道\n A[文件输入] --> B[Converter]\n B --> C[Preprocessor]\n C --> D[Embedder]\n D --> E[DocumentStore]\n end\n \n subgraph 检索管道\n F[用户查询] --> G[Retriever]\n G --> H[Prompt]\n H --> I[Generator]\n I --> J[答案输出]\n end\n \n E --> G\n```\n\n文档转换与预处理组件位于索引管道的前端，确保进入系统的文档具有良好的质量和格式。\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 配置与使用\n\n### 基础配置项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `split_by` | str | \"word\" | 分割单位：word、sentence、passage |\n| `split_length` | int | 100 | 每个块的单位数量 |\n| `split_overlap` | int | 0 | 块之间的重叠数量 |\n| `split_threshold` | int | 0 | 触发分割的最小阈值 |\n\n### 最佳实践\n\n1. **块大小选择**: 根据使用的 embedding 模型和 LLM 上下文窗口大小来调整\n2. **重叠设置**: 对于需要跨块理解的内容，适当设置重叠可以提高召回质量\n3. **元数据保留**: 在转换过程中保留重要的元数据信息，便于后续筛选和溯源\n4. **质量验证**: 在生产环境中添加转换质量检查步骤\n\n## 与其他组件的关系\n\n文档转换与预处理模块与 Haystack 的其他核心组件紧密协作：\n\n| 组件类型 | 关系描述 |\n|---------|---------|\n| **DocumentStore** | 存储处理后的文档，提供持久化支持 |\n| **Retriever** | 基于处理后的文档进行语义检索 |\n| **Generator** | 使用检索结果进行答案生成 |\n| **Embedder** | 将文本块转换为向量表示 |\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 安装与依赖\n\n文档转换与预处理功能已包含在主包中：\n\n```bash\npip install haystack-ai\n```\n\n对于特定的转换器，可能需要额外的依赖：\n\n```bash\n# PDF 转换\npip install haystack-ai[pdf]\n\n# Word 文档转换\npip install haystack-ai[docx]\n```\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 相关资源\n\n- [官方文档](https://docs.haystack.deepset.ai/)\n- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)\n- [API 参考文档](https://docs.haystack.deepset.ai/reference/)\n\n## 版本说明\n\n文档转换与预处理的 API 和行为在不同版本间可能存在差异。建议始终使用与 Haystack 主版本匹配的文档版本。\n\nSources: [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)\n\n---\n\n\n\n## 文本嵌入组件\n\n### Related Pages\n\nRelated topics: [LLM 生成器](#generators), [排序器与检索器](#rankers-retrievers)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n- [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n- [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n \n\n# 文本嵌入组件\n\n## 概述\n\n文本嵌入组件（Text Embedders）是 Haystack 框架中用于将文本转换为高维向量表示的核心组件。在检索增强生成（RAG）系统中，嵌入组件负责将文档和查询文本编码为语义向量，使得基于向量相似度的语义检索成为可能。\n\nHaystack 提供了多种文本嵌入组件，支持主流的 embedding 服务提供商，包括 OpenAI、HuggingFace API 等。这些组件可以作为流水线（Pipeline）的一部分，在文档索引阶段将文档内容向量化，在查询阶段将用户查询向量化。\n\n## 核心架构\n\n### 组件分类\n\nHaystack 的文本嵌入组件主要分为两大类：\n\n| 组件类型 | 用途 | 典型场景 |\n|---------|------|---------|\n| **Text Embedder** | 单文本嵌入 | 处理用户查询 |\n| **Document Embedder** | 文档集合嵌入 | 批量索引文档 |\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[文本输入] --> B[文本嵌入组件]\n B --> C{Provider 类型}\n C -->|OpenAI| D[OpenAITextEmbedder]\n C -->|HuggingFace| E[HuggingFaceAPITextEmbedder]\n D --> F[嵌入向量输出]\n E --> F\n F --> G[向量存储/检索]\n```\n\n## OpenAI 文本嵌入组件\n\n### 组件简介\n\n`OpenAITextEmbedder` 是 Haystack 官方提供的 OpenAI embedding 模型集成组件。该组件通过调用 OpenAI 的 embedding API 将文本转换为 1536 维的稠密向量（使用 `text-embedding-3-small` 模型）或 3072 维向量（使用 `text-embedding-3-large` 模型）。\n\nSources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n\n### 初始化参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `api_key` | `str` | 是 | - | OpenAI API 密钥 |\n| `model` | `str` | 否 | `\"text-embedding-3-small\"` | 使用的 embedding 模型 |\n| `api_base_url` | `str` | 否 | OpenAI 默认地址 | API 端点地址 |\n| `dimensions` | `int` | 否 | - | 输出向量维度（仅支持 3 系列模型）|\n| `timeout` | `float` | 否 | `60.0` | 请求超时时间（秒）|\n| `max_retries` | `int` | 否 | `5` | 最大重试次数 |\n\n### 使用示例\n\n```python\nfrom haystack.components.embedders import OpenAITextEmbedder\n\nembedder = OpenAITextEmbedder(\n api_key=\"your-api-key\",\n model=\"text-embedding-3-small\",\n dimensions=1024\n)\n\nresult = embedder.run(text=\"What is retrieval-augmented generation?\")\nprint(result[\"embedding\"][:5]) # 输出向量前5个维度\n```\n\n### 维度控制\n\n`text-embedding-3` 系列模型支持通过 `dimensions` 参数控制输出向量维度，这使得用户可以在保持语义表达能力的同时减少存储空间和计算成本。\n\nSources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n\n## HuggingFace API 文本嵌入组件\n\n### 组件简介\n\n`HuggingFaceAPITextEmbedder` 提供了对 HuggingFace Inference API 的集成支持。该组件允许用户使用 HuggingFace Hub 上托管的各种 embedding 模型，无需本地部署。\n\nSources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n\n### 初始化参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `api_key` | `str` | 是 | - | HuggingFace API 密钥 |\n| `model` | `str` | 是 | - | HuggingFace 模型 ID |\n| `token` | `str` | 否 | `None` | HuggingFace 访问令牌 |\n| `use_gpu` | `bool` | 否 | `True` | 是否使用 GPU（如果可用）|\n| `batch_size` | `int` | 否 | `32` | 批处理大小 |\n| `timeout` | `int` | 否 | `60` | 请求超时时间（秒）|\n| `truncate` | `bool` | 否 | `True` | 是否截断超长文本 |\n\n### 使用示例\n\n```python\nfrom haystack.components.embedders import HuggingFaceAPITextEmbedder\n\nembedder = HuggingFaceAPITextEmbedder(\n api_key=\"hf-xxxxx\",\n model=\"sentence-transformers/all-MiniLM-L6-v2\"\n)\n\nresult = embedder.run(text=\"Building RAG pipelines with Haystack\")\n```\n\n### 支持的模型\n\n该组件支持 HuggingFace Hub 上的所有支持 embedding 的模型，常见选择包括：\n\n| 模型 ID | 向量维度 | 说明 |\n|---------|---------|------|\n| `sentence-transformers/all-MiniLM-L6-v2` | 384 | 高效轻量模型 |\n| `sentence-transformers/all-mpnet-base-v2` | 768 | 高精度模型 |\n| `BAAI/bge-small-en-v1.5` | 512 | BGE 英文模型 |\n\nSources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n\n## 在流水线中使用嵌入组件\n\n### RAG 流水线架构\n\n```mermaid\ngraph LR\n A[用户查询] --> B[TextEmbedder]\n B --> C[向量检索器]\n D[文档库] --> E[DocumentEmbedder]\n E --> F[向量数据库]\n C --> G[上下文组装]\n G --> H[LLM 生成]\n H --> I[最终回答]\n```\n\n### 完整流水线示例\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.embedders import OpenAITextEmbedder\nfrom haystack.components.retrievers import InMemoryBM25Retriever\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化组件\ndocument_store = InMemoryDocumentStore()\nretriever = InMemoryBM25Retriever(document_store=document_store)\nembedder = OpenAITextEmbedder(api_key=\"your-key\")\n\n# 构建查询流水线\npipeline = Pipeline()\npipeline.add_component(\"embedder\", embedder)\npipeline.add_component(\"retriever\", retriever)\n\n# 连接组件\npipeline.connect(\"embedder.embedding\", \"retriever.query_embedding\")\n```\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n## 输出格式\n\n### 标准输出结构\n\n所有文本嵌入组件的 `run()` 方法返回统一格式的字典：\n\n| 输出键 | 类型 | 说明 |\n|--------|------|------|\n| `embedding` | `List[float]` | 文本的向量表示 |\n| `meta` | `Dict` | 元数据信息（如使用的模型）|\n\n```python\nresult = embedder.run(text=\"Hello, Haystack!\")\n# result = {\n# \"embedding\": [0.123, -0.456, 0.789, ...],\n# \"meta\": {\"model\": \"text-embedding-3-small\", \"usage\": {...}}\n# }\n```\n\n## 最佳实践\n\n### 1. 向量维度选择\n\n- 存储空间敏感场景：选择支持维度缩减的模型（如 `text-embedding-3`）\n- 高精度需求场景：使用高维度模型（如 `all-mpnet-base-v2`）\n- 平衡场景：使用中等维度模型（如 `all-MiniLM-L6-v2`）\n\n### 2. 批处理优化\n\n对于大量文档的索引任务，使用支持批处理的嵌入组件可以显著提升性能：\n\n```python\nfrom haystack.components.embedders import HuggingFaceAPITextEmbedder\n\nembedder = HuggingFaceAPITextEmbedder(\n model=\"sentence-transformers/all-MiniLM-L6-v2\",\n batch_size=64 # 根据 API 限制调整\n)\n```\n\n### 3. 错误处理\n\n建议在实际应用中实现重试机制和降级策略：\n\n```python\nfrom haystack.components.embedders import OpenAITextEmbedder\nfrom tenacity import retry, wait_exponential\n\n@retry(wait=wait_exponential(multiplier=1, min=2, max=10))\ndef embed_with_retry(embedder, text):\n return embedder.run(text=text)\n```\n\n## 相关组件\n\n| 组件类型 | 说明 |\n|---------|------|\n| `OpenAIDocumentEmbedder` | OpenAI 文档批量嵌入 |\n| `HuggingFaceAPIDocumentEmbedder` | HuggingFace 文档批量嵌入 |\n| `SentenceTransformersTextEmbedder` | 本地 SentenceTransformers 模型 |\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n## 扩展阅读\n\n- [Haystack 官方文档](https://docs.haystack.deepset.ai/docs/embedders)\n- [RAG 流水线教程](https://haystack.deepset.ai/cookbook)\n- [HuggingFace Embedding 模型列表](https://huggingface.co/models?pipeline_tag=feature-extraction)\n\n---\n\n\n\n## LLM 生成器\n\n### Related Pages\n\nRelated topics: [文本嵌入组件](#embedders), [Agent 代理系统](#agents)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [haystack/docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [haystack/README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [haystack/docs-website/docs/pipeline-components/generators.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)\n- [haystack/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)\n- [haystack/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)\n- [haystack/pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n \n\n# LLM 生成器\n\n## 概述\n\nLLM 生成器（LLM Generator）是 Haystack 框架中的核心组件之一，专门用于与大型语言模型（Large Language Models）进行交互。在 Haystack 2.x 架构中，生成器作为管道（Pipeline）的关键组件，负责接收输入提示（Prompt）并生成自然语言响应。\n\nSources: [README.md:1-10](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\nHaystack 是一个端到端的 LLM 框架，允许你构建由 LLMs、Transformer 模型、向量搜索等驱动的应用程序。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都可以将先进的嵌入模型和 LLMs 编排成管道，以构建端到端的 NLP 应用程序。\n\nSources: [docker/README.md:1-8](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n---\n\n## 架构与定位\n\n### 在管道中的角色\n\n在 Haystack 的整体架构中，LLM 生成器属于**管道组件（Pipeline Components）** 类别。Haystack 提供了多种管道组件，包括：\n\n| 组件类别 | 说明 |\n|---------|------|\n| 生成器（Generators） | 与 LLMs 交互，生成文本响应 |\n| 检索器（Retrievers） | 从向量数据库检索相关文档 |\n| 提示器（Prompters） | 构建和优化提示词 |\n| 工具（Tools） | 扩展 LLM 能力 |\n\nSources: [docs-website/README.md:50-60](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n### 设计理念\n\nHaystack 的生成器组件**专为上下文工程设计**，允许开发者灵活控制系统如何检索、排名、过滤、组合、结构化和路由信息，直到信息到达模型。\n\nSources: [README.md:40-45](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n---\n\n## 主要生成器实现\n\n### OpenAI Chat Generator\n\n`OpenAIChatGenerator` 是 Haystack 官方提供的与 OpenAI GPT 系列模型交互的组件。该生成器支持 OpenAI 的 Chat API，能够利用最新的 GPT-4 和 GPT-3.5-Turbo 模型。\n\n#### 核心特性\n\n- **流式响应支持**：支持实时流式输出，提升用户体验\n- **函数调用**：支持 OpenAI 的 function calling 功能\n- **多轮对话**：支持维护对话历史上下文\n- **温度控制**：可调节生成文本的随机性\n\nSources: [docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx:1-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)\n\n### Anthropic Chat Generator\n\n`AnthropicChatGenerator` 是与 Anthropic 公司 Claude 系列模型交互的专用生成器。Claude 模型以安全性高、输出可靠著称，特别适合需要严格遵循指令的应用场景。\n\n#### 核心特性\n\n- **长上下文窗口**：支持高达 200K tokens 的上下文\n- **Instruction Following**：优秀的指令遵循能力\n- **安全过滤**：内置内容安全过滤机制\n\nSources: [docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx:1-15](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)\n\n---\n\n## 生成器配置参数\n\n### 通用配置\n\n大多数 LLM 生成器共享以下核心配置参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `api_key` | str | API 密钥 | 环境变量 |\n| `model` | str | 模型名称 | 必填 |\n| `temperature` | float | 采样温度 (0-2) | 0.7 |\n| `max_tokens` | int | 最大生成 token 数 | 512 |\n| `streaming_callback` | Callable | 流式回调函数 | None |\n\nSources: [docs-website/docs/pipeline-components/generators.mdx:30-50](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)\n\n### API 参考文档\n\nHaystack 使用 [haystack-pydoc-tools](https://github.com/deepset-ai/haystack-pydoc-tools) 从代码的文档字符串自动生成 API 参考文档。所有 API 参考更新首先应用于不稳定文档版本，然后在发布新版本时提升到稳定版本。\n\nSources: [pydoc/README.md:1-15](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n## 工作流程\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[构建提示词 Prompt] --> B[发送到 LLM API]\n B --> C{选择生成器}\n C -->|OpenAI| D[OpenAIChatGenerator]\n C -->|Anthropic| E[AnthropicChatGenerator]\n C -->|其他| F[自定义生成器]\n D --> G[接收响应]\n E --> G\n F --> G\n G --> H[后处理响应]\n H --> I[输出结果]\n```\n\n### 集成到管道\n\n```mermaid\ngraph LR\n A[用户查询] --> B[检索器 Retriever]\n B --> C[检索相关文档]\n C --> D[提示构建器 PromptBuilder]\n D --> E[LLM 生成器]\n E --> F[最终响应]\n```\n\n---\n\n## 第三方集成\n\n### 贡献指南\n\nHaystack 欢迎社区贡献集成组件。除了核心项目外，集成组件可以在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 仓库中贡献。\n\nSources: [README.md:100-110](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 贡献方式\n\n社区可以通过以下方式贡献：\n\n1. **核心集成**：在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 贡献新的生成器实现\n2. **文档完善**：在 [haystack/docs-website](https://github.com/deepset-ai/haystack/tree/main/docs-website) 改进文档\n3. **问题修复**：修复 bug 或改进现有功能\n\n> 💡 **提示**：查看 [开放贡献的问题列表](https://github.com/orgs/deepset-ai/projects/14) 找到适合入门的任务\n\nSources: [README.md:105-115](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n---\n\n## 安装与配置\n\n### 安装方式\n\n#### 通过 pip 安装（推荐）\n\n```bash\npip install haystack-ai\n```\n\nSources: [README.md:20-25](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n#### 安装预发布版本\n\n```bash\npip install --pre haystack-ai\n```\n\n#### Docker 环境\n\n对于 Docker 环境，Haystack 提供了预装的基础镜像：\n\n```bash\ndocker pull deepset/haystack:base-\n```\n\nSources: [docker/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n---\n\n## 文档资源\n\n### 官方文档\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档站点 | [docs.haystack.deepset.ai](https://docs.haystack.deepset.ai) |\n| 入门指南 | [快速开始](https://haystack.deepset.ai/overview/quick-start) |\n| 教程 | [教程列表](https://haystack.deepset.ai/tutorials) |\n| Cookbook | [Haystack 食谱](https://haystack.deepset.ai/cookbook) |\n\nSources: [README.md:30-40](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 文档构建\n\n文档网站基于 Docusaurus 3 构建，使用以下命令启动本地开发服务器：\n\n```bash\ncd haystack/docs-website\nnpm install\nnpm start\n# 访问 http://localhost:3000\n```\n\nSources: [docs-website/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n---\n\n## 版本与兼容性\n\n### 版本管理\n\nHaystack 的文档版本与代码版本保持同步发布。当有新版本发布时，GitHub Actions 工作流会自动：\n\n1. 创建新的版本目录\n2. 更新版本配置文件\n3. 生成版本化的 API 参考文档\n\nSources: [docs-website/README.md:70-85](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n### llms.txt 文件\n\n文档站点为 AI 工具提供了一个 `llms.txt` 文件，由 `docusaurus-plugin-generate-llms-txt` 插件自动生成。该文件将所有文档内容连接成一个文本文件，便于 LLM 和其他工具消费。\n\nSources: [docs-website/README.md:95-110](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n---\n\n## 最佳实践\n\n### 1. 选择合适的模型\n\n根据应用场景选择生成器：\n\n- **需要高准确性**：选择 GPT-4 或 Claude 系列\n- **需要低成本**：选择 GPT-3.5-Turbo 或开源模型\n- **需要长上下文**：选择 Claude 200K 或 GPT-4-Turbo\n\n### 2. 提示工程\n\n充分利用 Haystack 的上下文工程能力：\n\n- 使用合适的 PromptBuilder 构建提示\n- 结合检索器提供相关上下文\n- 调整 temperature 控制输出稳定性\n\n### 3. 错误处理\n\n实现健壮的错误处理机制：\n\n```python\ntry:\n response = generator.run(prompt=my_prompt)\nexcept APIError as e:\n logger.error(f\"API Error: {e}\")\n # 实现重试逻辑\nexcept TimeoutError as e:\n logger.error(f\"Request timeout: {e}\")\n # 实现超时处理\n```\n\n---\n\n## 扩展阅读\n\n- [Haystack 官方文档](https://docs.haystack.deepset.ai)\n- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)\n- [Haystack Cookbooks](https://haystack.deepset.ai/cookbook)\n- [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations)\n\n---\n\n\n\n## 排序器与检索器\n\n### Related Pages\n\nRelated topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n- [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n- [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)\n \n\n# 排序器与检索器\n\n## 概述\n\n在 Haystack 框架中，**检索器（Retriever）** 和 **排序器（Ranker）** 是构建 RAG（检索增强生成）管道的核心组件。它们共同负责从大规模文档集合中找到最相关的信息，为大语言模型提供准确的上下文。\n\n### 核心功能定位\n\n| 组件类型 | 主要职责 | 输入 | 输出 |\n|---------|---------|------|------|\n| 检索器 (Retriever) | 从文档存储中快速召回候选文档 | 查询文本 | 候选文档列表 |\n| 排序器 (Ranker) | 对检索结果进行精细化排序 | 检索结果 + 查询 | 排序后的文档列表 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n\n---\n\n## 检索器（Retriever）\n\n### 工作原理\n\n检索器负责在大规模文档集合中快速定位相关信息。其核心目标是**高召回率（High Recall）**，即尽可能不遗漏相关文档。\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Retriever]\n B --> C[文档存储]\n C --> D[候选文档集合]\n D --> E[Top-K 文档]\n \n style A fill:#e1f5fe\n style E fill:#c8e6c9\n```\n\n### 主要类型\n\nHaystack 支持多种检索器实现：\n\n| 检索器类型 | 描述 | 适用场景 |\n|-----------|------|---------|\n| **EmbeddingRetriever** | 基于向量嵌入的语义检索 | 需要语义理解的场景 |\n| **BM25Retriever** | 基于词频的稀疏检索 | 关键词匹配为主的场景 |\n| **DensePassageRetriever** | 基于稠密段落嵌入 | 问答系统 |\n| **TfidfRetriever** | 基于 TF-IDF 算法 | 轻量级快速检索 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n\n### TextEmbeddingRetriever 详解\n\n`TextEmbeddingRetriever` 是最常用的检索器类型之一，它利用文本嵌入模型将查询和文档转换为向量表示，通过计算向量相似度来检索相关文档。\n\n#### 核心参数配置\n\n```python\nretriever = TextEmbeddingRetriever(\n embedding_backend=None, # 嵌入模型后端\n model_name_or_path=\"sentence-transformers/all-MiniLM-L6-v2\",\n api_key=None, # API 密钥（如使用云服务）\n top_k=10 # 返回的文档数量\n)\n```\n\n#### 工作流程\n\n```mermaid\ngraph TD\n A[查询文本] --> B[Embedding Model]\n C[文档库] --> D[Document Store]\n D --> E[预计算文档向量]\n B --> F[查询向量]\n F --> G[向量相似度计算]\n E --> G\n G --> H[Top-K 文档]\n \n style A fill:#e1f5fe\n style H fill:#c8e6c9\n```\n\nSources: [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)\n\n---\n\n## 排序器（Ranker）\n\n### 工作原理\n\n排序器接收检索器的候选结果，对文档与查询的相关性进行精细化评估和重新排序。其核心目标是**高精确率（High Precision）**，确保最相关的文档排在最前面。\n\n```mermaid\ngraph LR\n A[查询] --> B[Retriever]\n C[文档库] --> B\n B --> D[候选文档]\n D --> E[Ranker]\n E --> F[精排后文档]\n \n style D fill:#fff3e0\n style F fill:#c8e6c9\n```\n\n### 主要类型\n\n| 排序器类型 | 描述 | 特点 |\n|-----------|------|------|\n| **CohereRanker** | 使用 Cohere API 进行排序 | 云端服务，高精度 |\n| **OpenAIRanker** | 使用 OpenAI 模型排序 | 基于 GPT 技术 |\n| **SentenceTransformersRanker** | 使用本地 SentenceTransformer 模型 | 可本地部署 |\n| **TransformersRanker** | 基于 Transformer 的排序模型 | 支持多种预训练模型 |\n\nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n### 排序器参数\n\n```python\nranker = SentenceTransformersRanker(\n model_name_or_path=\"cross-encoder/ms-marco-MiniLM-L-12-v2\",\n top_k=5, # 最终返回的文档数量\n device=\"cpu\" # 运行设备\n)\n```\n\n---\n\n## 协同工作流程\n\n检索器和排序器通常在管道中串联使用，形成 **召回-排序（Recall-Rerank）** 范式：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Retriever]\n B --> C[初步候选文档
Top-K: 20-100]\n C --> D[Ranker]\n D --> E[精排文档
Top-K: 3-10]\n E --> F[LLM 生成答案]\n \n subgraph 召回阶段\n B\n end\n \n subgraph 排序阶段\n D\n end\n \n style A fill:#e1f5fe\n style F fill:#c8e6c9\n```\n\n### 典型配置模式\n\n| 阶段 | 组件 | Top-K 设置 | 说明 |\n|------|------|-----------|------|\n| 召回 | TextEmbeddingRetriever | 20-50 | 宽召回，确保不遗漏 |\n| 精排 | SentenceTransformersRanker | 3-5 | 精筛，提供高质量上下文 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx) \nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n---\n\n## 在 Pipeline 中使用\n\n### 完整示例\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.retrievers import TextEmbeddingRetriever\nfrom haystack.components.rankers import SentenceTransformersRanker\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化组件\ndocument_store = InMemoryDocumentStore()\nretriever = TextEmbeddingRetriever(top_k=20)\nranker = SentenceTransformersRanker(top_k=5)\n\n# 构建管道\npipeline = Pipeline()\npipeline.add_component(\"retriever\", retriever)\npipeline.add_component(\"ranker\", ranker)\n\n# 连接组件\npipeline.connect(\"retriever.documents\", \"ranker.documents\")\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n participant Query as 查询\n participant Retriever as 检索器\n participant Ranker as 排序器\n participant LLM as 大语言模型\n \n Query->>Retriever: 发送查询\n Retriever->>Ranker: 返回 Top-20 候选文档\n Ranker->>LLM: 返回 Top-5 精排文档\n LLM->>Query: 生成答案\n```\n\n---\n\n## 性能优化建议\n\n### 1. 检索器优化\n\n- **调整 Top-K 值**：根据文档库规模和召回需求设置合适的候选数量\n- **选择合适的嵌入模型**：在精度和速度之间权衡\n- **文档分段策略**：合理的分段大小可提升检索效果\n\n### 2. 排序器优化\n\n- **模型选择**：根据精度需求选择合适的排序模型\n- **Top-K 级联**：检索器的 K 值应大于排序器的 K 值（通常 4-10 倍）\n- **批处理**：批量处理可提升排序效率\n\n### 3. 整体策略\n\n| 场景 | 检索器 Top-K | 排序器 Top-K | 预期效果 |\n|------|-------------|-------------|---------|\n| 简单问答 | 10-20 | 3-5 | 快速响应 |\n| 复杂分析 | 50-100 | 5-10 | 高精度 |\n| 大规模检索 | 100-200 | 10-20 | 全面覆盖 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx) \nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n---\n\n## 最佳实践\n\n1. **先检索后排序**：不要跳过检索阶段直接使用排序器，这会导致性能问题\n2. **模型匹配**：尽量使用与检索器 Embedding 模型兼容的排序器\n3. **监控指标**：关注召回率和精确率，根据业务需求调整参数\n4. **文档预处理**：确保文档格式统一，预处理充分\n\n---\n\n\n\n## Agent 代理系统\n\n### Related Pages\n\nRelated topics: [LLM 生成器](#generators)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)\n- [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)\n- [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Agent 代理系统\n\n## 概述\n\nHaystack Agent 是框架中用于构建智能代理系统的核心组件，它使大型语言模型（LLM）能够通过工具调用、状态管理和多步骤推理来解决复杂任务。Agent 系统将 LLM 与外部工具、数据源和检索系统相结合，实现了自主决策和执行能力。\n\nSources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)\n\n## 架构设计\n\n### 核心组件\n\nAgent 系统由多个核心组件构成，每个组件负责特定的功能职责：\n\n| 组件 | 职责 | 关键特性 |\n|------|------|----------|\n| Agent | 主控制器 | 管理对话循环、决策制定、工具调用 |\n| Tool | 工具接口 | 封装外部功能、参数验证、结果处理 |\n| State | 状态管理 | 维护对话历史、跟踪执行上下文 |\n| Pipeline | 流程编排 | 串联多个组件、定义执行顺序 |\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)\n\n### 组件交互流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent 主控制器]\n B --> C{决策判断}\n C -->|调用工具| D[Tool 执行层]\n C -->|更新状态| E[State 管理层]\n C -->|生成响应| F[最终输出]\n D -->|工具结果| E\n E -->|状态更新| B\n B -->|继续迭代| C\n```\n\n## Agent 核心机制\n\n### 工具调用机制\n\nAgent 通过动态调用外部工具来扩展 LLM 的能力范围。工具可以是：\n\n- **检索工具**：连接向量数据库、执行相似性搜索\n- **API 工具**：调用外部服务、获取实时数据\n- **计算工具**：执行数据处理、格式转换\n- **自定义工具**：用户定义的任意功能\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:1-50)\n\n### 决策循环\n\nAgent 实现了自主决策循环，典型执行流程如下：\n\n```mermaid\ngraph LR\n A[接收任务] --> B[LLM 推理]\n B --> C{需要工具?}\n C -->|是| D[选择工具]\n D --> E[执行工具]\n E --> F[返回结果]\n F --> B\n C -->|否| G[生成回复]\n G --> H[返回用户]\n```\n\n## 状态管理系统\n\n### State 组件\n\nState 是 Agent 系统中负责维护执行状态的关键组件，它记录：\n\n- 对话历史记录\n- 工具调用记录\n- 中间执行结果\n- 上下文变量\n\nSources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)\n\n### 状态数据结构\n\nState 组件使用结构化数据模型来跟踪代理执行过程：\n\n```python\nclass AgentState:\n messages: List[Dict] # 对话历史\n tool_calls: List[Dict] # 工具调用记录\n intermediate_steps: List # 中间步骤\n context: Dict # 上下文变量\n```\n\n### 状态流转图\n\n```mermaid\ngraph TD\n A[初始状态] --> B[消息添加]\n B --> C{执行工具?}\n C -->|是| D[记录工具调用]\n D --> E[保存中间结果]\n E --> F[状态更新]\n F --> B\n C -->|否| G[标记完成]\n G --> H[最终状态]\n F --> H\n```\n\n## 使用示例\n\n### 基本 Agent 配置\n\n```python\nfrom haystack import Agent\n\nagent = Agent(\n tools=[retriever, calculator, web_searcher],\n prompt_template=\"你是一个有帮助的助手\"\n)\n```\n\n### 状态初始化\n\n```python\nfrom haystack.agents import AgentState\n\ninitial_state = AgentState(\n messages=[],\n tool_calls=[],\n context={}\n)\n```\n\nSources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx:1-30)\n\n## 与 Pipeline 集成\n\nAgent 可以作为 Pipeline 的组件进行编排，实现复杂的业务流程：\n\n```mermaid\ngraph LR\n A[用户查询] --> B[检索 Pipeline]\n B --> C[Agent 处理]\n C --> D{需要更多数据?}\n D -->|是| E[调用工具]\n E --> B\n D -->|否| F[生成回答]\n F --> G[返回结果]\n```\n\n### Pipeline 中的 Agent 配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| name | str | Agent 实例名称 |\n| tools | List[Tool] | 可用工具列表 |\n| prompt_template | str | 提示词模板 |\n| max_iterations | int | 最大迭代次数 |\n\nSources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx:1-50)\n\n## 最佳实践\n\n### 工具设计原则\n\n1. **单一职责**：每个工具只完成一个明确的任务\n2. **清晰的输入输出**：定义明确的参数和返回值\n3. **错误处理**：为工具添加适当的异常处理机制\n4. **文档完善**：提供清晰的使用说明和示例\n\n### 状态管理建议\n\n1. **定期清理**：避免状态数据无限增长\n2. **关键节点保存**：在重要步骤记录检查点\n3. **上下文优化**：仅保留必要的上下文信息\n\n## 配置选项\n\n### 核心参数表\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `tools` | [] | 关联的工具列表 |\n| `max_steps` | 10 | 最大执行步数 |\n| `tool_call_limit` | 50 | 工具调用上限 |\n| `streaming` | true | 是否启用流式输出 |\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:50-80)\n\n## 相关资源\n\n- [Agent 概念文档](./concepts/agents.mdx)\n- [Agent API 参考](./pipeline-components/agents-1/agent.mdx)\n- [State 组件参考](./pipeline-components/agents-1/state.mdx)\n- [Haystack 官方文档](https://docs.haystack.deepset.ai)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：deepset-ai/haystack\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown\n\n\n",
"markdown_key": "haystack",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:221654678",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/deepset-ai/haystack"
},
{
"evidence_id": "art_3da5693908af4dd08c207de6b8f3fd4b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/deepset-ai/haystack#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "haystack 说明书",
"toc": [
"Wiki Documentation for https://github.com/deepset-ai/haystack",
"Table of Contents",
"Haystack 简介",
"项目概述",
"核心特性",
"技术架构",
"安装与部署",
"文档系统",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# haystack - Doramagic AI Context Pack\n\n> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。\n\n## 项目\n\n- canonical_name: `deepset-ai/haystack`\n- capability: Open-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.\n- expected_user_outcome: Open-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.\n\n## 基础边界\n\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。\n- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。\n- publish_status: `publishable`\n- blocking_gaps: none\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Haystack 简介**：importance `high`\n - source_paths: README.md, VERSION.txt\n- **快速入门指南**：importance `high`\n - source_paths: docs-website/docs/overview/installation.mdx, docs-website/docs/overview/get-started.mdx\n- **核心概念**：importance `high`\n - source_paths: docs-website/docs/concepts/concepts-overview.mdx, docs-website/docs/concepts/components.mdx, docs-website/docs/concepts/pipelines.mdx, docs-website/docs/concepts/data-classes.mdx\n- **Pipeline 系统**：importance `high`\n - source_paths: docs-website/docs/concepts/pipelines/creating-pipelines.mdx, docs-website/docs/concepts/pipelines/debugging-pipelines.mdx, docs-website/docs/concepts/pipelines/serialization.mdx, docs-website/docs/concepts/pipelines/asyncpipeline.mdx\n- **文档存储系统**：importance `high`\n - source_paths: docs-website/docs/concepts/document-store.mdx, docs-website/docs/document-stores/inmemorydocumentstore.mdx, docs-website/docs/document-stores/qdrant-document-store.mdx, docs-website/docs/document-stores/weaviatedocumentstore.mdx\n- **文档转换与预处理**：importance `medium`\n - source_paths: docs-website/docs/pipeline-components/converters.mdx, docs-website/docs/pipeline-components/preprocessors.mdx, docs-website/docs/pipeline-components/preprocessors/documentsplitter.mdx\n- **文本嵌入组件**：importance `high`\n - source_paths: docs-website/docs/pipeline-components/embedders.mdx, docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx, docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx\n- **LLM 生成器**：importance `high`\n - source_paths: docs-website/docs/pipeline-components/generators.mdx, docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx, docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：deepset-ai/haystack\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# Wiki Documentation for https://github.com/deepset-ai/haystack\n\nGenerated on: 2026-05-10 15:07:55 UTC\n\n## Table of Contents\n\n- [Haystack 简介](#introduction)\n- [快速入门指南](#quick-start)\n- [核心概念](#core-concepts)\n- [Pipeline 系统](#pipeline-system)\n- [文档存储系统](#document-stores)\n- [文档转换与预处理](#converters-preprocessors)\n- [文本嵌入组件](#embedders)\n- [LLM 生成器](#generators)\n- [排序器与检索器](#rankers-retrievers)\n- [Agent 代理系统](#agents)\n\n\n\n## Haystack 简介\n\n### Related Pages\n\nRelated topics: [快速入门指南](#quick-start), [核心概念](#core-concepts)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n- [docs-website/src/components/CopyDropdown/index.tsx](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/components/CopyDropdown/index.tsx)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Haystack 简介\n\n## 项目概述\n\nHaystack 是一个端到端的 LLM（大型语言模型）框架，允许开发者构建由 LLMs、Transformer 模型和向量搜索等技术支持的应用。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都能将最先进的嵌入模型和 LLMs 编排成流水线，构建完整的 NLP 应用。Sources: [README.md:1]()\n\nHaystack 由 deepset 公司开发和维护，是一个开源项目，支持生产级别的 AI 应用构建。该框架的设计理念是提供对上下文工程的完全控制，让开发者能够精确管理信息的检索、排序、过滤、组合、结构化和路由过程。Sources: [README.md:40-42]()\n\n## 核心特性\n\nHaystack 框架具有以下核心特性，使其成为构建 LLM 应用的理想选择：\n\n### 为上下文工程而构建\n\nHaystack 允许设计灵活的系统，开发者可以明确控制信息在到达模型之前的处理方式。通过定义流水线和代理工作流，可以精确控制检索、内存、工具和路由的行为。Sources: [README.md:40-45]()\n\n### 生产级别支持\n\n框架经过生产环境验证，被众多知名企业和机构采用，包括 Apple、Meta、Databricks、NVIDIA、Intel 等科技巨头，以及欧盟委员会等公共部门机构。Sources: [README.md:97-104]()\n\n## 技术架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Haystack Pipeline]\n B --> C[检索组件]\n B --> D[LLM 组件]\n B --> E[Agent 组件]\n C --> F[向量数据库]\n D --> G[外部 LLM API]\n E --> H[工具调用]\n F --> I[文档存储]\n G --> J[模型输出]\n H --> K[执行结果]\n```\n\n### 组件架构\n\nHaystack 的组件架构设计支持多种集成方式，主要包括以下几类：\n\n| 组件类别 | 说明 | 典型用途 |\n|---------|------|---------|\n| 检索组件 | 从文档存储中检索相关信息 | RAG 场景的信息获取 |\n| LLM 组件 | 与外部 LLM API 交互 | 生成答案和摘要 |\n| Agent 组件 | 自主决策和工具调用 | 复杂任务的自动化执行 |\n| 管道组件 | 连接和组织各组件 | 构建完整的处理流程 |\n\n## 安装与部署\n\n### pip 安装\n\n获取 Haystack 最简单的方式是通过 pip 安装：\n\n```sh\npip install haystack-ai\n```\n\n对于想尝试最新功能的用户，可以安装预发布版本：\n\n```sh\npip install --pre haystack-ai\n```\n\nSources: [README.md:23-29]()\n\n### Docker 部署\n\nHaystack 提供官方 Docker 镜像，支持多平台架构。镜像通过 BuildKit 构建，使用 `bake` 进行流程编排。\n\n| 镜像名称 | 说明 |\n|---------|------|\n| `haystack:base-` | 包含预装 Haystack 的 Python 工作环境 |\n\n构建自定义镜像的命令如下：\n\n```sh\ndocker buildx bake base\n```\n\n如需使用特定分支或标签构建：\n\n```sh\nHAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache\n```\n\nSources: [docker/README.md:1-45]()\n\n## 文档系统\n\n### 文档网站结构\n\nHaystack 的文档网站基于 Docusaurus 3 构建，托管在 https://docs.haystack.deepset.ai。文档系统采用版本化管理，支持多版本并行维护。Sources: [docs-website/README.md:1-15]()\n\n```mermaid\ngraph LR\n A[docs/] -->|主要文档| B[guides/]\n A --> C[concepts/]\n A --> D[pipeline-components/]\n E[reference/] -->|自动生成| F[API 文档]\n G[versioned_docs/] -->|版本快照| H[历史版本]\n```\n\n### 文档目录结构\n\n| 目录 | 用途 |\n|-----|------|\n| `docs/` | 主要文档（指南、教程、概念） |\n| `docs/_templates/` | 作者模板（构建时排除） |\n| `docs/concepts/` | Haystack 核心概念 |\n| `docs/pipeline-components/` | 组件文档 |\n| `reference/` | API 参考（自动生成） |\n| `versioned_docs/` | 版本化文档副本 |\n| `src/` | React 组件和自定义代码 |\n\nSources: [docs-website/README.md:24-40]()\n\n### llms.txt 生成\n\n文档网站支持生成 `llms.txt` 文件，方便 AI 工具消费文档内容。该功能由 `docusaurus-plugin-generate-llms-txt` 插件实现。Sources: [docs-website/README.md:83-98]()\n\n| 生成方式 | 命令 |\n|---------|------|\n| 开发服务器 | `npm run start` |\n| 生产构建 | `npm run build` |\n| 手动生成 | `npm run generate-llms-txt` |\n\n## API 参考\n\nHaystack 使用 haystack-pydoc-tools 从代码文档字符串生成 Markdown 格式的 API 参考文档。所有 API 文档更新都先在 unstable docs 版本中发布，在新版本发布时才会合并到 stable docs 版本。Sources: [pydoc/README.md:1-18]()\n\n### API 文档工作流\n\n```mermaid\ngraph LR\n A[代码文档字符串] -->|GitHub Actions| B[docusaurus_sync.yml]\n B --> C[API Markdown 生成]\n C --> D[unstable docs]\n D -->|版本发布| E[stable docs]\n```\n\n如需为新模块生成 API 页面，需在 `pydoc` 目录中创建 `.yml` 配置文件来指定生成规则。Sources: [pydoc/README.md:14-18]()\n\n## CI/CD 与自动化\n\n### 持续集成\n\nHaystack 项目维护严格的 CI/CD 流程，包括：\n\n| 检查项 | 状态徽章 |\n|-------|---------|\n| 测试 | Tests workflow |\n| 类型检查 | Mypy |\n| 覆盖率 | Coverage badge |\n| 代码规范 | Ruff |\n| 许可证合规 | License compliance |\n\nSources: [README.md:5-16]()\n\n### 文档版本管理\n\n文档版本发布与 Haystack 版本发布完全自动化，通过以下工作流实现：\n\n| 工作流 | 功能 |\n|-------|------|\n| `promote_unstable_docs.yml` | Haystack 发布期间自动触发 |\n| `minor_version_release.yml` | 创建新版本目录并更新版本配置 |\n\n贡献者无需手动创建或管理版本，版本化流程完全自动化。Sources: [docs-website/README.md:64-72]()\n\n## 导航系统\n\n### 导航高亮机制\n\n文档网站的导航系统采用智能高亮机制，确保用户在浏览不同文档类别时获得正确的导航状态。系统通过以下规则防止跨高亮：\n\n```mermaid\ngraph TD\n A[当前页面路径] --> B{检查路径前缀}\n B -->|docs/| C{当前插件}\n B -->|reference/| D{当前插件}\n C -->|DEFAULT_PLUGIN_ID| E[高亮 Docs]\n C -->|reference| F[不高亮]\n D -->|reference| G[高亮 API Reference]\n D -->|DEFAULT_PLUGIN_ID| H[不高亮]\n```\n\n关键路径前缀定义如下：\n\n```javascript\nconst REFERENCE_PATH_PREFIX = '/reference/';\nconst DOCS_PATH_PREFIX = '/docs/';\n```\n\nSources: [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js:1-50]()\n\n## 搜索功能\n\n### 搜索系统架构\n\n文档网站实现了自定义搜索系统，支持按类型筛选和分组展示结果。Sources: [docs-website/src/theme/SearchBar.js:1-80]()\n\n| 功能 | 说明 |\n|-----|------|\n| 全文搜索 | 基于文档内容的语义搜索 |\n| 类型过滤 | 支持按文档类型筛选 |\n| 结果分组 | 按页面分组显示匹配结果 |\n| 高亮显示 | 显示搜索词上下文片段 |\n\n搜索结果处理流程：\n\n```mermaid\ngraph TD\n A[搜索查询] --> B[文档分组]\n B --> C[计算相关性得分]\n C --> D[按得分排序]\n D --> E[生成摘要片段]\n E --> F[返回结果列表]\n```\n\n## 社区与贡献\n\n### 贡献渠道\n\nHaystack 欢迎社区贡献，包括但不限于：\n\n| 贡献类型 | 仓库 |\n|---------|------|\n| 核心功能开发 | main/haystack |\n| 集成组件 | haystack-core-integrations |\n| 文档改进 | haystack/docs-website |\n\nSources: [README.md:111-121]()\n\n### 用户案例\n\nHaystack 被广泛应用于各行业：\n\n| 行业 | 代表用户 |\n|-----|---------|\n| 科技与 AI 基础设施 | Apple, Meta, Databricks, NVIDIA, Intel |\n| 公共部门 | 欧盟委员会 |\n| 企业 AI | 众多生产级 AI 系统团队 |\n\nSources: [README.md:97-104]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| GitHub 仓库 | https://github.com/deepset-ai/haystack |\n| 示例代码库 | https://github.com/deepset-ai/haystack-cookbook |\n| Discord 社区 | https://discord.gg/VBpFzsgacQ |\n| 贡献指南 | CONTRIBUTING.md |\n\n---\n\n\n\n## 快速入门指南\n\n### Related Pages\n\nRelated topics: [Haystack 简介](#introduction), [Pipeline 系统](#pipeline-system)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n \n\n# 快速入门指南\n\nHaystack 是一个开源框架，用于构建生产级 LLM 应用，支持检索增强生成（RAG）、文档搜索、问答系统等功能。本指南将帮助你在最短时间内完成环境搭建并运行第一个 Haystack 应用。\n\n## 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.8+ | 推荐使用 Python 3.9 或更高版本 |\n| Node.js | 18+ | 仅在使用文档网站时需要 |\n| pip | 最新版 | Python 包管理器 |\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 安装方式\n\nHaystack 提供多种安装方式，满足不同场景需求。\n\n### 使用 pip 安装（推荐）\n\n```bash\n# 安装稳定版本\npip install haystack-ai\n\n# 安装预发布版本（包含最新功能）\npip install --pre haystack-ai\n```\n\nSources: [README.md:1](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 使用 Docker\n\nHaystack 提供预配置的 Docker 镜像，适合快速部署和开发环境隔离：\n\n```bash\n# 构建基础镜像\ndocker buildx bake base\n\n# 使用自定义版本构建\nHAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache\n```\n\nDocker 镜像包含预装的 Python 环境和 Haystack，可直接作为基础镜像使用。\n\nSources: [docker/README.md:1](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n## 项目结构概览\n\n```\nhaystack/\n├── docs-website/ # Docusaurus 文档网站\n│ ├── docs/ # 主文档（指南、教程、概念）\n│ ├── reference/ # API 参考（自动生成）\n│ └── src/ # React 组件\n├── docker/ # Docker 配置\n├── examples/ # 示例代码（已迁移至独立仓库）\n└── pydoc/ # API 文档生成配置\n```\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 创建第一个应用\n\n### 基本组件架构\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Pipeline]\n B --> C[Retriever 检索器]\n B --> D[Prompt 模板]\n C --> E[Document Store 文档库]\n D --> F[LLM 大语言模型]\n E --> G[检索结果]\n G --> D\n F --> H[最终答案]\n```\n\n### 核心组件说明\n\n| 组件 | 功能 | 常见实现 |\n|------|------|----------|\n| Pipeline | 连接各组件的工作流编排 | `Pipeline`, `RootNode` |\n| Retriever | 从文档库检索相关文档 | `BM25Retriever`, `EmbeddingRetriever` |\n| Document Store | 存储和索引文档向量 | `InMemoryDocumentStore`, `OpenSearchDocumentStore` |\n| Prompt | 定义提示词模板 | `PromptTemplate`, `ChatPromptBuilder` |\n| LLM | 大语言模型接口 | `OpenAIChat`, `HuggingFaceTGI` |\n\n## 文档网站本地开发\n\n如果你需要为 Haystack 文档做贡献或自定义文档站点：\n\n### 环境准备\n\n```bash\n# 克隆仓库\ngit clone https://github.com/deepset-ai/haystack.git\ncd haystack/docs-website\n\n# 安装依赖\nnpm install\n```\n\n### 启动开发服务器\n\n```bash\nnpm start\n# 文档网站地址: http://localhost:3000\n```\n\n### 生产环境检查\n\n```bash\nnpm run build && npm run serve\n```\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 常见任务参考\n\n| 任务 | 命令/操作 |\n|------|-----------|\n| 编辑文档页面 | 修改 `docs/` 或 `versioned_docs/` 下的文件 |\n| 添加侧边栏项目 | 修改 `sidebars.js` 添加文档 ID |\n| 生成 API 参考 | 提交 `.yml` 配置文件到 `pydoc/` 目录 |\n| 生成 llms.txt | `npm run generate-llms-txt` |\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 下一步\n\n- 查看完整[安装文档](https://docs.haystack.deepset.ai/docs/installation)了解更多安装选项\n- 阅读 [\"What is Haystack?\"](https://haystack.deepset.ai/overview/intro) 了解核心概念\n- 访问 [Cookbook](https://haystack.deepset.ai/cookbook) 获取高级用例和示例代码\n- 示例代码已迁移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库\n\nSources: [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md), [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 版本管理\n\nHaystack 文档版本与代码版本同步发布，完全自动化管理：\n\n```mermaid\ngraph LR\n A[代码提交] --> B[GitHub Workflow]\n B --> C[API 参考同步]\n B --> D[版本化文档生成]\n C --> E[Unstable Docs]\n D --> E\n E --> F[发布时同步到 Stable]\n```\n\n自动化工作流包括：\n- `promote_unstable_docs.yml` - 发布时自动触发\n- `minor_version_release.yml` - 创建新版本目录\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 技术栈\n\n| 类别 | 技术 |\n|------|------|\n| 核心框架 | Python |\n| 文档系统 | Docusaurus 3 |\n| API 文档生成 | haystack-pydoc-tools |\n| CI/CD | GitHub Actions |\n| 容器化 | Docker BuildKit |\n\nSources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n\n\n## 核心概念\n\n### Related Pages\n\nRelated topics: [Pipeline 系统](#pipeline-system), [Agent 代理系统](#agents)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)\n- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)\n\n**Note**: The originally requested concept documentation files (`concepts-overview.mdx`, `components.mdx`, `pipelines.mdx`, `data-classes.mdx`) were not present in the provided repository context. This wiki page is constructed based on available documentation files and repository structure information.\n \n\n# 核心概念\n\nHaystack 是一个端到端的 LLM（大型语言模型）框架，用于构建由 LLMs、Transformer 模型和向量搜索驱动的应用程序。本文档介绍 Haystack 的核心概念，帮助开发者理解框架的架构设计和主要组成部分。\n\n## 概述\n\nHaystack 2.x 是一个专为上下文工程设计的开源框架，其核心目标是帮助开发者构建灵活的系统，实现对信息检索、排序、过滤、组合、结构化和路由的精确控制。Sources: [README.md:1-5]()\n\n框架的主要特性包括：\n\n- **上下文工程导向**：设计灵活的系统，显式控制信息如何被检索、排序、过滤、组合、结构化和路由\n- **RAG 和 Agents 支持**：构建生产级别的检索增强生成系统和智能代理\n- **模块化架构**：通过组件和管道实现高度可定制的工作流\n- **多源集成**：支持与各种 LLM 提供商、向量数据库和文档处理工具的集成\n\nSources: [README.md:1-5]()\n\n## 核心组件\n\nHaystack 的架构围绕三个主要概念展开：组件（Components）、管道（Pipelines）和数据类（Data Classes）。\n\n```mermaid\ngraph TD\n A[Haystack 应用] --> B[管道 Pipeline]\n B --> C[组件 Components]\n C --> D[数据类 Data Classes]\n E[LLM 提供商] --> B\n F[向量数据库] --> B\n G[文档源] --> B\n```\n\n### 组件（Components）\n\n组件是 Haystack 管道中的基本构建块。每个组件负责执行特定的 NLP 任务，如文档检索、文本生成、文本嵌入等。\n\n**组件类型分类：**\n\n| 类型 | 功能描述 | 示例 |\n|------|----------|------|\n| 检索器（Retrievers） | 从文档库中检索相关文档 | BM25Retriever, EmbeddingRetriever |\n| 读取器（Readers） | 从检索到的文档中提取答案 | ExtractiveReader, GenerativeReader |\n| 生成器（Generators） | 使用 LLM 生成文本 | OpenAIGenerator, HuggingFaceTGI |\n| 排序器（Rerankers） | 对检索结果进行重新排序 | SentenceTransformersReranker |\n| 工具（Tools） | 为代理提供可调用功能 | SearchTool, CalculatorTool |\n| 存储器（Memory） | 管理对话历史和上下文 | ChatMemory |\n\n### 管道（Pipelines）\n\n管道是连接和组织组件的核心机制。管道定义了数据在组件之间的流动方式，使得复杂的 NLP 工作流得以实现。\n\n**管道类型：**\n\n1. **搜索管道（Search Pipeline）**：用于文档检索和问答场景\n2. **索引管道（Indexing Pipeline）**：用于处理和存储文档\n3. **代理管道（Agent Pipeline）**：用于构建对话代理和工作流自动化\n\n**管道配置特点：**\n\n- 支持条件路由：根据条件选择不同的处理路径\n- 并行执行：多个组件可同时处理数据\n- 动态输入/输出：组件可接收多个输入并产生多个输出\n- 可序列化：管道配置可保存为 YAML 文件\n\nSources: [README.md:1-5]()\n\n### 数据类（Data Classes）\n\nHaystack 使用标准化的数据类来表示文档、响应和元数据。这些数据类确保组件之间的数据传递具有一致性和类型安全性。\n\n**核心数据类：**\n\n| 数据类 | 用途 |\n|--------|------|\n| Document | 表示文本文档及其元数据 |\n| Answer | 表示从文档中提取或生成的答案 |\n| Speech | 处理语音相关的输入输出 |\n| Trace | 跟踪管道执行过程 |\n| ToolMessage | 工具调用结果的消息格式 |\n\nSources: [README.md:1-5]()\n\n## 文档处理流程\n\nHaystack 支持完整的文档处理流程，从原始文档输入到最终答案输出：\n\n```mermaid\ngraph LR\n A[文档输入] --> B[文档转换器]\n B --> C[文档存储]\n C --> D[检索器]\n D --> E[读取器]\n E --> F[答案输出]\n \n G[用户查询] --> D\n```\n\n### 索引阶段\n\n1. **文档加载**：从各种来源加载文档（PDF、HTML、Markdown 等）\n2. **文档转换**：将文档分割成适合处理的块\n3. **向量化**：使用嵌入模型将文本转换为向量表示\n4. **存储**：将文档和向量存储到向量数据库\n\n### 检索阶段\n\n1. **查询处理**：将用户问题转换为向量表示\n2. **相似度搜索**：在向量数据库中查找最相关的文档\n3. **结果排序**：可选地使用排序器优化结果顺序\n\n### 回答阶段\n\n1. **上下文构建**：将检索到的文档组合成上下文\n2. **答案生成**：使用 LLM 基于上下文生成答案\n3. **后处理**：格式化输出结果\n\nSources: [README.md:1-5]()\n\n## 代理系统\n\nHaystack 的代理系统允许构建能够自主决策和执行复杂任务对话式 AI 应用。\n\n**代理核心功能：**\n\n- **工具调用**：代理可以调用多种工具完成特定任务\n- **对话记忆**：维护对话历史以支持多轮对话\n- **路由决策**：根据上下文选择下一步行动\n- **函数调用**：与外部 API 和服务交互\n\n```mermaid\ngraph TD\n A[用户输入] --> B[代理 Agent]\n B --> C{决策}\n C -->|调用工具| D[工具执行]\n D --> E[结果处理]\n E --> B\n C -->|生成回复| F[最终响应]\n E --> F\n```\n\nSources: [README.md:1-5]()\n\n## 版本管理\n\nHaystack 文档支持多版本管理，包括：\n\n| 版本类型 | 说明 |\n|----------|------|\n| Next (Unreleased) | 未发布的开发版本文档 |\n| Current (Stable) | 当前稳定版本文档 |\n| Past Versions | 历史版本文档存档 |\n\n开发者可以通过文档网站的版本选择器访问不同版本的文档。Sources: [docs-website/src/pages/versions.js:1-40]()\n\n## 快速入门\n\n安装 Haystack 最简单的方式是通过 pip：\n\n```bash\npip install haystack-ai\n```\n\n如需安装预发布版本以体验最新功能：\n\n```bash\npip install --pre haystack-ai\n```\n\nSources: [README.md:1-5]()\n\n## 文档资源\n\nHaystack 提供完整的文档资源支持：\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| 入门指南 | https://haystack.deepset.ai/overview/quick-start |\n| 教程 | https://haystack.deepset.ai/tutorials |\n| Cookbook | https://haystack.deepset.ai/cookbook |\n| API 参考 | 通过文档网站 reference 部分访问 |\n\nSources: [README.md:1-5]()\n\n## 相关仓库\n\nHaystack 生态系统包括多个相关仓库：\n\n| 仓库 | 用途 |\n|------|------|\n| haystack-core-integrations | 核心集成组件 |\n| haystack-cookbook | 示例代码和最佳实践 |\n| haystack-pydoc-tools | API 文档生成工具 |\n\n示例代码已移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库。Sources: [examples/README.md:1-5]()\n\n## 总结\n\nHaystack 的核心概念围绕组件、管道和数据类三个主要构建块展开。通过这些抽象，开发者可以灵活地构建复杂的 LLM 应用，实现从简单的问答系统到复杂的多代理工作流。框架的模块化设计使得每个组件都可以独立使用或组合使用，满足不同场景的需求。\n\n---\n\n\n\n## Pipeline 系统\n\n### Related Pages\n\nRelated topics: [核心概念](#core-concepts), [文本嵌入组件](#embedders), [LLM 生成器](#generators)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Pipeline 系统\n\n## 概述\n\nHaystack 是一个开源的 LLM（大型语言模型）框架，而 Pipeline 系统是其核心架构组件。Pipeline 允许开发者设计灵活的系统，对信息的检索、排名、过滤、组合、结构化和路由过程实现精确控制，确保这些操作在到达模型之前得到妥善管理。\n\nPipeline 系统支持定义管线和代理工作流，使检索、记忆、工具调用和生成过程透明且可追踪。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 核心特性\n\n### 上下文工程导向\n\nPipeline 系统专为上下文工程（Context Engineering）而构建，提供了对数据流的显式控制能力。开发者可以精确控制信息从输入到输出的整个生命周期。\n\n### 循环、分支和条件逻辑\n\nPipeline 支持添加循环（loops）、分支（branches）和条件逻辑（conditional logic），以精确控制上下文如何在 Pipeline 和代理工作流中流动。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 透明性和可追溯性\n\n所有通过 Pipeline 的数据流动都是透明的，开发者可以追踪每个处理步骤，便于调试和优化。\n\n## 架构流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Pipeline 入口]\n B --> C{路由决策}\n C -->|检索路径| D[检索组件]\n C -->|工具调用| E[工具组件]\n C -->|生成路径| F[生成组件]\n D --> G[结果处理]\n E --> G\n F --> G\n G --> H{条件判断}\n H -->|继续| B\n H -->|结束| I[最终输出]\n```\n\n## Pipeline 类型\n\n| 类型 | 描述 | 典型用例 |\n|------|------|----------|\n| 基础 Pipeline | 线性处理流程 | 简单 RAG 流程 |\n| 条件 Pipeline | 包含条件分支 | 路由决策 |\n| 循环 Pipeline | 支持循环迭代 | 迭代优化 |\n| 异步 Pipeline | 异步执行支持 | 高并发场景 |\n\n## 文档资源\n\nHaystack 提供了全面的 Pipeline 相关文档，涵盖以下主题：\n\n| 文档主题 | 路径 |\n|----------|------|\n| 创建 Pipeline | `docs/concepts/pipelines/creating-pipelines.mdx` |\n| 调试 Pipeline | `docs/concepts/pipelines/debugging-pipelines.mdx` |\n| 序列化 | `docs/concepts/pipelines/serialization.mdx` |\n| 异步 Pipeline | `docs/concepts/pipelines/asyncpipeline.mdx` |\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 与其他组件的集成\n\nPipeline 系统与以下核心组件紧密集成：\n\n- **检索组件（Retrieval）**：处理信息检索和排名\n- **工具组件（Tools）**：支持工具调用功能\n- **记忆组件（Memory）**：管理对话上下文状态\n- **生成组件（Generation）**：处理最终输出生成\n\n## 与 Hayhooks 的集成\n\n如需将 Pipeline 部署为 REST API 或 MCP 服务器，可以使用 [Hayhooks](https://github.com/deepset-ai/hayhooks)。Hayhooks 提供了一种简单的方式将 Pipeline 和代理包装为自定义逻辑，并通过 HTTP 端点或 MCP 协议暴露它们。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 开发环境\n\n文档网站使用 Docusaurus 3 构建，支持实时预览 Pipeline 文档变更。开发环境要求：\n\n- **Node.js**：18 或更高版本\n- **包管理器**：npm 或 Yarn\n\n快速启动命令：\n```bash\ncd haystack/docs-website\nnpm install\nnpm start\n```\n\n预览地址：`http://localhost:3000`\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 版本管理\n\nPipeline 文档与 Haystack 版本同步发布，通过以下自动化工作流管理：\n\n- `promote_unstable_docs.yml`：在 Haystack 发布期间自动触发\n- `minor_version_release.yml`：创建新版本目录并更新版本配置\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 相关链接\n\n| 资源 | 地址 |\n|------|------|\n| 官方文档 | https://docs.haystack.deepset.ai |\n| 概念指南 | https://docs.haystack.deepset.ai/docs/concepts |\n| 快速开始 | https://haystack.deepset.ai/overview/quick-start |\n| GitHub 仓库 | https://github.com/deepset-ai/haystack |\n\n---\n\n\n\n## 文档存储系统\n\n### Related Pages\n\nRelated topics: [文档转换与预处理](#converters-preprocessors), [排序器与检索器](#rankers-retrievers)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n- [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx)\n- [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n- [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n \n\n# 文档存储系统\n\n## 概述\n\nHaystack 的文档存储系统（Document Store）是构建检索增强生成（RAG）和其他 NLP 应用的核心基础设施。文档存储系统负责存储、索引和管理文档向量嵌入（Embeddings），为后续的语义搜索和相似性检索提供支持。\n\n在 Haystack 框架中，文档存储系统扮演着数据持久化层的角色，它与检索管道（Retrieval Pipeline）紧密集成，使得大规模文档集合能够被高效查询。Sources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[文档输入] --> B[文档转换器 DocumentConverter]\n B --> C[Document 对象]\n C --> D[文档存储系统 DocumentStore]\n D --> E[向量数据库]\n F[查询请求] --> G[向量化器 Embedder]\n G --> H[查询向量]\n H --> D\n D --> I[相似性检索]\n I --> J[检索结果]\n```\n\n### 文档存储系统类型\n\nHaystack 支持多种文档存储系统实现，每种实现针对不同的使用场景和规模进行了优化。\n\n| 存储类型 | 适用场景 | 特点 | 文档路径 |\n|---------|---------|------|---------|\n| InMemoryDocumentStore | 开发测试 | 轻量级、易用、无需外部依赖 | docs-website/docs/document-stores/inmemorydocumentstore.mdx |\n| QdrantDocumentStore | 生产环境 | 高性能、混合检索、支持过滤 | docs-website/docs/document-stores/qdrant-document-store.mdx |\n| WeaviateDocumentStore | 生产环境 | 向量化和检索一体化、语义搜索 | docs-website/docs/document-stores/weaviatedocumentstore.mdx |\n\nSources: [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx), [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx), [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n\n## 文档管理\n\n### 写入操作\n\n文档存储系统支持批量写入文档，这一操作通常与文档转换器配合使用。\n\n```mermaid\ngraph LR\n A[源文档] --> B[DocumentConverter]\n B --> C[Document 列表]\n C --> D[write_documents]\n D --> E[DocumentStore]\n E --> F[向量索引]\n```\n\n关键写入方法包括：\n\n| 方法 | 参数 | 说明 |\n|-----|------|-----|\n| write_documents | documents, batch_size | 批量写入文档，支持分批处理 |\n| delete_documents | document_ids | 根据 ID 删除文档 |\n| delete_all_documents | | 清空所有文档 |\n\nSources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n### 检索操作\n\n文档存储系统提供多种检索方式，支持不同的查询策略。\n\n| 检索类型 | 说明 | 典型应用 |\n|---------|------|---------|\n| 相似性检索 | 基于向量余弦相似度或欧氏距离 | 语义搜索、问答系统 |\n| 过滤检索 | 支持元数据条件过滤 | 领域特定检索 |\n| 混合检索 | 结合关键词和向量检索 | 精确度要求高的场景 |\n\nSources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n\n## 配置与集成\n\n### 基础配置\n\n文档存储系统在 Haystack Pipeline 中通过组件方式集成。以下是典型的配置模式：\n\n```python\nfrom haystack import Pipeline\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化文档存储\ndocument_store = InMemoryDocumentStore(\n embedding_dim=768,\n return_embedding=True\n)\n\n# 创建管道\npipeline = Pipeline()\npipeline.add_component(\"document_store\", document_store)\n```\n\n### 环境变量\n\n文档存储系统的某些配置可以通过环境变量进行控制，这在不同部署环境中提供了灵活性。\n\n| 环境变量 | 说明 | 适用存储 |\n|---------|------|---------|\n| DOCS_PRODUCT | 文档产品标识 | 文档网站生成 |\n| HAYSTACK_VERSION | Haystack 版本 | Docker 镜像构建 |\n\nSources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md), [docs-website/src/theme/Html.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/Html.js)\n\n## 生产环境部署\n\n### Docker 部署\n\nHaystack 提供预配置的 Docker 镜像，适用于生产环境部署。\n\n| 镜像 | 说明 | 使用场景 |\n|-----|------|---------|\n| haystack:base-\\ | 基础 Python 环境 | 需要自定义依赖的部署 |\n\n镜像构建使用 BuildKit 和 bake 工具：\n\n```bash\ndocker buildx bake base\n```\n\nSources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n### 外部向量数据库集成\n\n对于大规模生产环境，建议使用专门的向量数据库：\n\n#### Qdrant 集成\n\nQdrant 是一个高性能的向量相似性搜索引擎，支持：\n\n- 混合检索能力\n- 元数据过滤\n- 稀疏和密集向量支持\n- 地理空间查询\n\nSources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)\n\n#### Weaviate 集成\n\nWeaviate 是另一个企业级向量数据库，特点包括：\n\n- 内置向量化功能\n- 原生图结构支持\n- 多租户架构\n- 实时索引更新\n\nSources: [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)\n\n## 最佳实践\n\n### 开发与生产环境分离\n\n| 环境 | 推荐存储 | 原因 |\n|-----|---------|-----|\n| 开发/测试 | InMemoryDocumentStore | 快速启动、无额外依赖 |\n| 生产 | Qdrant/Weaviate | 高性能、可扩展 |\n\n### 性能优化建议\n\n1. **批量处理**：使用批量写入减少网络开销\n2. **索引优化**：根据数据规模选择合适的向量维度\n3. **缓存策略**：对频繁查询使用结果缓存\n4. **分片策略**：大规模数据考虑分片部署\n\nSources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)\n\n## 文档资源\n\nHaystack 文档网站提供完整的文档存储系统参考资料，访问地址：https://docs.haystack.deepset.ai\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\nAPI 参考文档通过 haystack-pydoc-tools 自动从代码 docstring 生成，确保与代码库同步更新。\n\nSources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n\n\n## 文档转换与预处理\n\n### Related Pages\n\nRelated topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n \n\n# 文档转换与预处理\n\n> **注意**: 本页面基于 Haystack 仓库中可用的文档和代码文件编写。由于某些具体实现文件（如 `converters.mdx`、`preprocessors.mdx`、`documentsplitter.mdx`）未包含在当前检索上下文中，部分技术细节基于 Haystack 整体架构和已知功能的推断。\n\n## 概述\n\nHaystack 是一个开源 LLM 框架，用于构建生产级 AI 应用，其核心功能之一是**文档转换与预处理**。这一功能模块负责将各种格式的原始文档转换为可供检索和处理的结构化文档对象。\n\n文档转换与预处理是检索增强生成（RAG）管道中的关键环节，直接影响后续检索质量和生成效果。Haystack 提供了完整的文档处理工具链，涵盖从原始文件到可检索文本的完整转换流程。\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[原始文档] --> B[文档转换器]\n B --> C[文档对象 Document]\n C --> D[预处理器]\n D --> E[清洗后的文档]\n E --> F[向量化]\n F --> G[向量存储]\n \n B1[PDF] --> B\n B2[Word] --> B\n B3[HTML] --> B\n B4[TXT] --> B\n B5[Markdown] --> B\n \n D1[文本清洗] --> D\n D2[文档分割] --> D\n D3[元数据提取] --> D\n```\n\n## 文档转换器 (Converters)\n\n文档转换器是将各种格式的原始文件转换为 Haystack `Document` 对象的组件。Haystack 支持多种输入格式的转换。\n\n### 支持的转换格式\n\n| 格式类型 | 描述 | 典型用途 |\n|---------|------|---------|\n| PDF | 便携式文档格式 | 合同、报告、论文 |\n| Word (.docx) | Microsoft Word 文档 | 商业文档、合同 |\n| HTML | 超文本标记语言 | 网页内容抓取 |\n| TXT | 纯文本文件 | 日志、配置文档 |\n| Markdown | 轻量级标记语言 | 技术文档、README |\n\n### 转换器组件\n\n文档转换器作为 Pipeline 组件集成到 Haystack 系统中，可以直接连接到索引管道进行处理。\n\n```\nPipeline 结构示例:\nDocumentConverter → Preprocessor → DocumentStore\n```\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 预处理器 (Preprocessors)\n\n预处理器负责对转换后的文档进行进一步处理，确保数据质量并优化检索性能。\n\n### 核心预处理功能\n\n#### 文档分割 (Document Splitting)\n\n文档分割是将长文档拆分为较小块的常用技术，用于：\n\n- **适配模型上下文窗口**: 大多数 LLM 有 token 数量限制\n- **提高检索精度**: 较小的文本块更容易匹配用户查询\n- **优化召回率**: 相关内容更容易被准确检索\n\n#### 文本清洗 (Text Cleaning)\n\n文本清洗功能包括：\n\n- 移除多余空白字符\n- 标准化标点符号\n- 处理特殊字符和编码问题\n- 提取或清理元数据\n\n### 预处理工作流\n\n```mermaid\ngraph LR\n A[原始文本] --> B[分句]\n B --> C[块划分]\n C --> D[重叠处理]\n D --> E[元数据附加]\n E --> F[最终文档块]\n \n C --> G[大小检查]\n G -->|过大| H[递归分割]\n H --> D\n G -->|合适| D\n```\n\n## 文档对象模型\n\nHaystack 使用 `Document` 类作为核心数据结构来表示处理后的文档。\n\n```python\nDocument(\n id: str,\n content: str,\n meta: Dict[str, Any]\n)\n```\n\n| 属性 | 类型 | 描述 |\n|-----|------|------|\n| `id` | str | 文档唯一标识符 |\n| `content` | str | 文档文本内容 |\n| `meta` | Dict | 元数据字典，可包含来源、页码、标题等信息 |\n\n## 与管道组件的集成\n\n### 索引管道中的位置\n\n```mermaid\ngraph TD\n subgraph 索引管道\n A[文件输入] --> B[Converter]\n B --> C[Preprocessor]\n C --> D[Embedder]\n D --> E[DocumentStore]\n end\n \n subgraph 检索管道\n F[用户查询] --> G[Retriever]\n G --> H[Prompt]\n H --> I[Generator]\n I --> J[答案输出]\n end\n \n E --> G\n```\n\n文档转换与预处理组件位于索引管道的前端，确保进入系统的文档具有良好的质量和格式。\n\nSources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n## 配置与使用\n\n### 基础配置项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `split_by` | str | \"word\" | 分割单位：word、sentence、passage |\n| `split_length` | int | 100 | 每个块的单位数量 |\n| `split_overlap` | int | 0 | 块之间的重叠数量 |\n| `split_threshold` | int | 0 | 触发分割的最小阈值 |\n\n### 最佳实践\n\n1. **块大小选择**: 根据使用的 embedding 模型和 LLM 上下文窗口大小来调整\n2. **重叠设置**: 对于需要跨块理解的内容，适当设置重叠可以提高召回质量\n3. **元数据保留**: 在转换过程中保留重要的元数据信息，便于后续筛选和溯源\n4. **质量验证**: 在生产环境中添加转换质量检查步骤\n\n## 与其他组件的关系\n\n文档转换与预处理模块与 Haystack 的其他核心组件紧密协作：\n\n| 组件类型 | 关系描述 |\n|---------|---------|\n| **DocumentStore** | 存储处理后的文档，提供持久化支持 |\n| **Retriever** | 基于处理后的文档进行语义检索 |\n| **Generator** | 使用检索结果进行答案生成 |\n| **Embedder** | 将文本块转换为向量表示 |\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 安装与依赖\n\n文档转换与预处理功能已包含在主包中：\n\n```bash\npip install haystack-ai\n```\n\n对于特定的转换器，可能需要额外的依赖：\n\n```bash\n# PDF 转换\npip install haystack-ai[pdf]\n\n# Word 文档转换\npip install haystack-ai[docx]\n```\n\nSources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n## 相关资源\n\n- [官方文档](https://docs.haystack.deepset.ai/)\n- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)\n- [API 参考文档](https://docs.haystack.deepset.ai/reference/)\n\n## 版本说明\n\n文档转换与预处理的 API 和行为在不同版本间可能存在差异。建议始终使用与 Haystack 主版本匹配的文档版本。\n\nSources: [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)\n\n---\n\n\n\n## 文本嵌入组件\n\n### Related Pages\n\nRelated topics: [LLM 生成器](#generators), [排序器与检索器](#rankers-retrievers)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n- [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n- [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n \n\n# 文本嵌入组件\n\n## 概述\n\n文本嵌入组件（Text Embedders）是 Haystack 框架中用于将文本转换为高维向量表示的核心组件。在检索增强生成（RAG）系统中，嵌入组件负责将文档和查询文本编码为语义向量，使得基于向量相似度的语义检索成为可能。\n\nHaystack 提供了多种文本嵌入组件，支持主流的 embedding 服务提供商，包括 OpenAI、HuggingFace API 等。这些组件可以作为流水线（Pipeline）的一部分，在文档索引阶段将文档内容向量化，在查询阶段将用户查询向量化。\n\n## 核心架构\n\n### 组件分类\n\nHaystack 的文本嵌入组件主要分为两大类：\n\n| 组件类型 | 用途 | 典型场景 |\n|---------|------|---------|\n| **Text Embedder** | 单文本嵌入 | 处理用户查询 |\n| **Document Embedder** | 文档集合嵌入 | 批量索引文档 |\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[文本输入] --> B[文本嵌入组件]\n B --> C{Provider 类型}\n C -->|OpenAI| D[OpenAITextEmbedder]\n C -->|HuggingFace| E[HuggingFaceAPITextEmbedder]\n D --> F[嵌入向量输出]\n E --> F\n F --> G[向量存储/检索]\n```\n\n## OpenAI 文本嵌入组件\n\n### 组件简介\n\n`OpenAITextEmbedder` 是 Haystack 官方提供的 OpenAI embedding 模型集成组件。该组件通过调用 OpenAI 的 embedding API 将文本转换为 1536 维的稠密向量（使用 `text-embedding-3-small` 模型）或 3072 维向量（使用 `text-embedding-3-large` 模型）。\n\nSources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n\n### 初始化参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `api_key` | `str` | 是 | - | OpenAI API 密钥 |\n| `model` | `str` | 否 | `\"text-embedding-3-small\"` | 使用的 embedding 模型 |\n| `api_base_url` | `str` | 否 | OpenAI 默认地址 | API 端点地址 |\n| `dimensions` | `int` | 否 | - | 输出向量维度（仅支持 3 系列模型）|\n| `timeout` | `float` | 否 | `60.0` | 请求超时时间（秒）|\n| `max_retries` | `int` | 否 | `5` | 最大重试次数 |\n\n### 使用示例\n\n```python\nfrom haystack.components.embedders import OpenAITextEmbedder\n\nembedder = OpenAITextEmbedder(\n api_key=\"your-api-key\",\n model=\"text-embedding-3-small\",\n dimensions=1024\n)\n\nresult = embedder.run(text=\"What is retrieval-augmented generation?\")\nprint(result[\"embedding\"][:5]) # 输出向量前5个维度\n```\n\n### 维度控制\n\n`text-embedding-3` 系列模型支持通过 `dimensions` 参数控制输出向量维度，这使得用户可以在保持语义表达能力的同时减少存储空间和计算成本。\n\nSources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)\n\n## HuggingFace API 文本嵌入组件\n\n### 组件简介\n\n`HuggingFaceAPITextEmbedder` 提供了对 HuggingFace Inference API 的集成支持。该组件允许用户使用 HuggingFace Hub 上托管的各种 embedding 模型，无需本地部署。\n\nSources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n\n### 初始化参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| `api_key` | `str` | 是 | - | HuggingFace API 密钥 |\n| `model` | `str` | 是 | - | HuggingFace 模型 ID |\n| `token` | `str` | 否 | `None` | HuggingFace 访问令牌 |\n| `use_gpu` | `bool` | 否 | `True` | 是否使用 GPU（如果可用）|\n| `batch_size` | `int` | 否 | `32` | 批处理大小 |\n| `timeout` | `int` | 否 | `60` | 请求超时时间（秒）|\n| `truncate` | `bool` | 否 | `True` | 是否截断超长文本 |\n\n### 使用示例\n\n```python\nfrom haystack.components.embedders import HuggingFaceAPITextEmbedder\n\nembedder = HuggingFaceAPITextEmbedder(\n api_key=\"hf-xxxxx\",\n model=\"sentence-transformers/all-MiniLM-L6-v2\"\n)\n\nresult = embedder.run(text=\"Building RAG pipelines with Haystack\")\n```\n\n### 支持的模型\n\n该组件支持 HuggingFace Hub 上的所有支持 embedding 的模型，常见选择包括：\n\n| 模型 ID | 向量维度 | 说明 |\n|---------|---------|------|\n| `sentence-transformers/all-MiniLM-L6-v2` | 384 | 高效轻量模型 |\n| `sentence-transformers/all-mpnet-base-v2` | 768 | 高精度模型 |\n| `BAAI/bge-small-en-v1.5` | 512 | BGE 英文模型 |\n\nSources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)\n\n## 在流水线中使用嵌入组件\n\n### RAG 流水线架构\n\n```mermaid\ngraph LR\n A[用户查询] --> B[TextEmbedder]\n B --> C[向量检索器]\n D[文档库] --> E[DocumentEmbedder]\n E --> F[向量数据库]\n C --> G[上下文组装]\n G --> H[LLM 生成]\n H --> I[最终回答]\n```\n\n### 完整流水线示例\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.embedders import OpenAITextEmbedder\nfrom haystack.components.retrievers import InMemoryBM25Retriever\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化组件\ndocument_store = InMemoryDocumentStore()\nretriever = InMemoryBM25Retriever(document_store=document_store)\nembedder = OpenAITextEmbedder(api_key=\"your-key\")\n\n# 构建查询流水线\npipeline = Pipeline()\npipeline.add_component(\"embedder\", embedder)\npipeline.add_component(\"retriever\", retriever)\n\n# 连接组件\npipeline.connect(\"embedder.embedding\", \"retriever.query_embedding\")\n```\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n## 输出格式\n\n### 标准输出结构\n\n所有文本嵌入组件的 `run()` 方法返回统一格式的字典：\n\n| 输出键 | 类型 | 说明 |\n|--------|------|------|\n| `embedding` | `List[float]` | 文本的向量表示 |\n| `meta` | `Dict` | 元数据信息（如使用的模型）|\n\n```python\nresult = embedder.run(text=\"Hello, Haystack!\")\n# result = {\n# \"embedding\": [0.123, -0.456, 0.789, ...],\n# \"meta\": {\"model\": \"text-embedding-3-small\", \"usage\": {...}}\n# }\n```\n\n## 最佳实践\n\n### 1. 向量维度选择\n\n- 存储空间敏感场景：选择支持维度缩减的模型（如 `text-embedding-3`）\n- 高精度需求场景：使用高维度模型（如 `all-mpnet-base-v2`）\n- 平衡场景：使用中等维度模型（如 `all-MiniLM-L6-v2`）\n\n### 2. 批处理优化\n\n对于大量文档的索引任务，使用支持批处理的嵌入组件可以显著提升性能：\n\n```python\nfrom haystack.components.embedders import HuggingFaceAPITextEmbedder\n\nembedder = HuggingFaceAPITextEmbedder(\n model=\"sentence-transformers/all-MiniLM-L6-v2\",\n batch_size=64 # 根据 API 限制调整\n)\n```\n\n### 3. 错误处理\n\n建议在实际应用中实现重试机制和降级策略：\n\n```python\nfrom haystack.components.embedders import OpenAITextEmbedder\nfrom tenacity import retry, wait_exponential\n\n@retry(wait=wait_exponential(multiplier=1, min=2, max=10))\ndef embed_with_retry(embedder, text):\n return embedder.run(text=text)\n```\n\n## 相关组件\n\n| 组件类型 | 说明 |\n|---------|------|\n| `OpenAIDocumentEmbedder` | OpenAI 文档批量嵌入 |\n| `HuggingFaceAPIDocumentEmbedder` | HuggingFace 文档批量嵌入 |\n| `SentenceTransformersTextEmbedder` | 本地 SentenceTransformers 模型 |\n\nSources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)\n\n## 扩展阅读\n\n- [Haystack 官方文档](https://docs.haystack.deepset.ai/docs/embedders)\n- [RAG 流水线教程](https://haystack.deepset.ai/cookbook)\n- [HuggingFace Embedding 模型列表](https://huggingface.co/models?pipeline_tag=feature-extraction)\n\n---\n\n\n\n## LLM 生成器\n\n### Related Pages\n\nRelated topics: [文本嵌入组件](#embedders), [Agent 代理系统](#agents)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [haystack/docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n- [haystack/README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)\n- [haystack/docs-website/docs/pipeline-components/generators.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)\n- [haystack/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)\n- [haystack/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)\n- [haystack/pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n \n\n# LLM 生成器\n\n## 概述\n\nLLM 生成器（LLM Generator）是 Haystack 框架中的核心组件之一，专门用于与大型语言模型（Large Language Models）进行交互。在 Haystack 2.x 架构中，生成器作为管道（Pipeline）的关键组件，负责接收输入提示（Prompt）并生成自然语言响应。\n\nSources: [README.md:1-10](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\nHaystack 是一个端到端的 LLM 框架，允许你构建由 LLMs、Transformer 模型、向量搜索等驱动的应用程序。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都可以将先进的嵌入模型和 LLMs 编排成管道，以构建端到端的 NLP 应用程序。\n\nSources: [docker/README.md:1-8](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n---\n\n## 架构与定位\n\n### 在管道中的角色\n\n在 Haystack 的整体架构中，LLM 生成器属于**管道组件（Pipeline Components）** 类别。Haystack 提供了多种管道组件，包括：\n\n| 组件类别 | 说明 |\n|---------|------|\n| 生成器（Generators） | 与 LLMs 交互，生成文本响应 |\n| 检索器（Retrievers） | 从向量数据库检索相关文档 |\n| 提示器（Prompters） | 构建和优化提示词 |\n| 工具（Tools） | 扩展 LLM 能力 |\n\nSources: [docs-website/README.md:50-60](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n### 设计理念\n\nHaystack 的生成器组件**专为上下文工程设计**，允许开发者灵活控制系统如何检索、排名、过滤、组合、结构化和路由信息，直到信息到达模型。\n\nSources: [README.md:40-45](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n---\n\n## 主要生成器实现\n\n### OpenAI Chat Generator\n\n`OpenAIChatGenerator` 是 Haystack 官方提供的与 OpenAI GPT 系列模型交互的组件。该生成器支持 OpenAI 的 Chat API，能够利用最新的 GPT-4 和 GPT-3.5-Turbo 模型。\n\n#### 核心特性\n\n- **流式响应支持**：支持实时流式输出，提升用户体验\n- **函数调用**：支持 OpenAI 的 function calling 功能\n- **多轮对话**：支持维护对话历史上下文\n- **温度控制**：可调节生成文本的随机性\n\nSources: [docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx:1-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)\n\n### Anthropic Chat Generator\n\n`AnthropicChatGenerator` 是与 Anthropic 公司 Claude 系列模型交互的专用生成器。Claude 模型以安全性高、输出可靠著称，特别适合需要严格遵循指令的应用场景。\n\n#### 核心特性\n\n- **长上下文窗口**：支持高达 200K tokens 的上下文\n- **Instruction Following**：优秀的指令遵循能力\n- **安全过滤**：内置内容安全过滤机制\n\nSources: [docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx:1-15](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)\n\n---\n\n## 生成器配置参数\n\n### 通用配置\n\n大多数 LLM 生成器共享以下核心配置参数：\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `api_key` | str | API 密钥 | 环境变量 |\n| `model` | str | 模型名称 | 必填 |\n| `temperature` | float | 采样温度 (0-2) | 0.7 |\n| `max_tokens` | int | 最大生成 token 数 | 512 |\n| `streaming_callback` | Callable | 流式回调函数 | None |\n\nSources: [docs-website/docs/pipeline-components/generators.mdx:30-50](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)\n\n### API 参考文档\n\nHaystack 使用 [haystack-pydoc-tools](https://github.com/deepset-ai/haystack-pydoc-tools) 从代码的文档字符串自动生成 API 参考文档。所有 API 参考更新首先应用于不稳定文档版本，然后在发布新版本时提升到稳定版本。\n\nSources: [pydoc/README.md:1-15](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)\n\n---\n\n## 工作流程\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[构建提示词 Prompt] --> B[发送到 LLM API]\n B --> C{选择生成器}\n C -->|OpenAI| D[OpenAIChatGenerator]\n C -->|Anthropic| E[AnthropicChatGenerator]\n C -->|其他| F[自定义生成器]\n D --> G[接收响应]\n E --> G\n F --> G\n G --> H[后处理响应]\n H --> I[输出结果]\n```\n\n### 集成到管道\n\n```mermaid\ngraph LR\n A[用户查询] --> B[检索器 Retriever]\n B --> C[检索相关文档]\n C --> D[提示构建器 PromptBuilder]\n D --> E[LLM 生成器]\n E --> F[最终响应]\n```\n\n---\n\n## 第三方集成\n\n### 贡献指南\n\nHaystack 欢迎社区贡献集成组件。除了核心项目外，集成组件可以在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 仓库中贡献。\n\nSources: [README.md:100-110](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 贡献方式\n\n社区可以通过以下方式贡献：\n\n1. **核心集成**：在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 贡献新的生成器实现\n2. **文档完善**：在 [haystack/docs-website](https://github.com/deepset-ai/haystack/tree/main/docs-website) 改进文档\n3. **问题修复**：修复 bug 或改进现有功能\n\n> 💡 **提示**：查看 [开放贡献的问题列表](https://github.com/orgs/deepset-ai/projects/14) 找到适合入门的任务\n\nSources: [README.md:105-115](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n---\n\n## 安装与配置\n\n### 安装方式\n\n#### 通过 pip 安装（推荐）\n\n```bash\npip install haystack-ai\n```\n\nSources: [README.md:20-25](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n#### 安装预发布版本\n\n```bash\npip install --pre haystack-ai\n```\n\n#### Docker 环境\n\n对于 Docker 环境，Haystack 提供了预装的基础镜像：\n\n```bash\ndocker pull deepset/haystack:base-\n```\n\nSources: [docker/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)\n\n---\n\n## 文档资源\n\n### 官方文档\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档站点 | [docs.haystack.deepset.ai](https://docs.haystack.deepset.ai) |\n| 入门指南 | [快速开始](https://haystack.deepset.ai/overview/quick-start) |\n| 教程 | [教程列表](https://haystack.deepset.ai/tutorials) |\n| Cookbook | [Haystack 食谱](https://haystack.deepset.ai/cookbook) |\n\nSources: [README.md:30-40](https://github.com/deepset-ai/haystack/blob/main/README.md)\n\n### 文档构建\n\n文档网站基于 Docusaurus 3 构建，使用以下命令启动本地开发服务器：\n\n```bash\ncd haystack/docs-website\nnpm install\nnpm start\n# 访问 http://localhost:3000\n```\n\nSources: [docs-website/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n---\n\n## 版本与兼容性\n\n### 版本管理\n\nHaystack 的文档版本与代码版本保持同步发布。当有新版本发布时，GitHub Actions 工作流会自动：\n\n1. 创建新的版本目录\n2. 更新版本配置文件\n3. 生成版本化的 API 参考文档\n\nSources: [docs-website/README.md:70-85](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n### llms.txt 文件\n\n文档站点为 AI 工具提供了一个 `llms.txt` 文件，由 `docusaurus-plugin-generate-llms-txt` 插件自动生成。该文件将所有文档内容连接成一个文本文件，便于 LLM 和其他工具消费。\n\nSources: [docs-website/README.md:95-110](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)\n\n---\n\n## 最佳实践\n\n### 1. 选择合适的模型\n\n根据应用场景选择生成器：\n\n- **需要高准确性**：选择 GPT-4 或 Claude 系列\n- **需要低成本**：选择 GPT-3.5-Turbo 或开源模型\n- **需要长上下文**：选择 Claude 200K 或 GPT-4-Turbo\n\n### 2. 提示工程\n\n充分利用 Haystack 的上下文工程能力：\n\n- 使用合适的 PromptBuilder 构建提示\n- 结合检索器提供相关上下文\n- 调整 temperature 控制输出稳定性\n\n### 3. 错误处理\n\n实现健壮的错误处理机制：\n\n```python\ntry:\n response = generator.run(prompt=my_prompt)\nexcept APIError as e:\n logger.error(f\"API Error: {e}\")\n # 实现重试逻辑\nexcept TimeoutError as e:\n logger.error(f\"Request timeout: {e}\")\n # 实现超时处理\n```\n\n---\n\n## 扩展阅读\n\n- [Haystack 官方文档](https://docs.haystack.deepset.ai)\n- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)\n- [Haystack Cookbooks](https://haystack.deepset.ai/cookbook)\n- [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations)\n\n---\n\n\n\n## 排序器与检索器\n\n### Related Pages\n\nRelated topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n- [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n- [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)\n \n\n# 排序器与检索器\n\n## 概述\n\n在 Haystack 框架中，**检索器（Retriever）** 和 **排序器（Ranker）** 是构建 RAG（检索增强生成）管道的核心组件。它们共同负责从大规模文档集合中找到最相关的信息，为大语言模型提供准确的上下文。\n\n### 核心功能定位\n\n| 组件类型 | 主要职责 | 输入 | 输出 |\n|---------|---------|------|------|\n| 检索器 (Retriever) | 从文档存储中快速召回候选文档 | 查询文本 | 候选文档列表 |\n| 排序器 (Ranker) | 对检索结果进行精细化排序 | 检索结果 + 查询 | 排序后的文档列表 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n\n---\n\n## 检索器（Retriever）\n\n### 工作原理\n\n检索器负责在大规模文档集合中快速定位相关信息。其核心目标是**高召回率（High Recall）**，即尽可能不遗漏相关文档。\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Retriever]\n B --> C[文档存储]\n C --> D[候选文档集合]\n D --> E[Top-K 文档]\n \n style A fill:#e1f5fe\n style E fill:#c8e6c9\n```\n\n### 主要类型\n\nHaystack 支持多种检索器实现：\n\n| 检索器类型 | 描述 | 适用场景 |\n|-----------|------|---------|\n| **EmbeddingRetriever** | 基于向量嵌入的语义检索 | 需要语义理解的场景 |\n| **BM25Retriever** | 基于词频的稀疏检索 | 关键词匹配为主的场景 |\n| **DensePassageRetriever** | 基于稠密段落嵌入 | 问答系统 |\n| **TfidfRetriever** | 基于 TF-IDF 算法 | 轻量级快速检索 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)\n\n### TextEmbeddingRetriever 详解\n\n`TextEmbeddingRetriever` 是最常用的检索器类型之一，它利用文本嵌入模型将查询和文档转换为向量表示，通过计算向量相似度来检索相关文档。\n\n#### 核心参数配置\n\n```python\nretriever = TextEmbeddingRetriever(\n embedding_backend=None, # 嵌入模型后端\n model_name_or_path=\"sentence-transformers/all-MiniLM-L6-v2\",\n api_key=None, # API 密钥（如使用云服务）\n top_k=10 # 返回的文档数量\n)\n```\n\n#### 工作流程\n\n```mermaid\ngraph TD\n A[查询文本] --> B[Embedding Model]\n C[文档库] --> D[Document Store]\n D --> E[预计算文档向量]\n B --> F[查询向量]\n F --> G[向量相似度计算]\n E --> G\n G --> H[Top-K 文档]\n \n style A fill:#e1f5fe\n style H fill:#c8e6c9\n```\n\nSources: [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)\n\n---\n\n## 排序器（Ranker）\n\n### 工作原理\n\n排序器接收检索器的候选结果，对文档与查询的相关性进行精细化评估和重新排序。其核心目标是**高精确率（High Precision）**，确保最相关的文档排在最前面。\n\n```mermaid\ngraph LR\n A[查询] --> B[Retriever]\n C[文档库] --> B\n B --> D[候选文档]\n D --> E[Ranker]\n E --> F[精排后文档]\n \n style D fill:#fff3e0\n style F fill:#c8e6c9\n```\n\n### 主要类型\n\n| 排序器类型 | 描述 | 特点 |\n|-----------|------|------|\n| **CohereRanker** | 使用 Cohere API 进行排序 | 云端服务，高精度 |\n| **OpenAIRanker** | 使用 OpenAI 模型排序 | 基于 GPT 技术 |\n| **SentenceTransformersRanker** | 使用本地 SentenceTransformer 模型 | 可本地部署 |\n| **TransformersRanker** | 基于 Transformer 的排序模型 | 支持多种预训练模型 |\n\nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n### 排序器参数\n\n```python\nranker = SentenceTransformersRanker(\n model_name_or_path=\"cross-encoder/ms-marco-MiniLM-L-12-v2\",\n top_k=5, # 最终返回的文档数量\n device=\"cpu\" # 运行设备\n)\n```\n\n---\n\n## 协同工作流程\n\n检索器和排序器通常在管道中串联使用，形成 **召回-排序（Recall-Rerank）** 范式：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Retriever]\n B --> C[初步候选文档
Top-K: 20-100]\n C --> D[Ranker]\n D --> E[精排文档
Top-K: 3-10]\n E --> F[LLM 生成答案]\n \n subgraph 召回阶段\n B\n end\n \n subgraph 排序阶段\n D\n end\n \n style A fill:#e1f5fe\n style F fill:#c8e6c9\n```\n\n### 典型配置模式\n\n| 阶段 | 组件 | Top-K 设置 | 说明 |\n|------|------|-----------|------|\n| 召回 | TextEmbeddingRetriever | 20-50 | 宽召回，确保不遗漏 |\n| 精排 | SentenceTransformersRanker | 3-5 | 精筛，提供高质量上下文 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx) \nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n---\n\n## 在 Pipeline 中使用\n\n### 完整示例\n\n```python\nfrom haystack import Pipeline\nfrom haystack.components.retrievers import TextEmbeddingRetriever\nfrom haystack.components.rankers import SentenceTransformersRanker\nfrom haystack.document_stores import InMemoryDocumentStore\n\n# 初始化组件\ndocument_store = InMemoryDocumentStore()\nretriever = TextEmbeddingRetriever(top_k=20)\nranker = SentenceTransformersRanker(top_k=5)\n\n# 构建管道\npipeline = Pipeline()\npipeline.add_component(\"retriever\", retriever)\npipeline.add_component(\"ranker\", ranker)\n\n# 连接组件\npipeline.connect(\"retriever.documents\", \"ranker.documents\")\n```\n\n### 数据流\n\n```mermaid\nsequenceDiagram\n participant Query as 查询\n participant Retriever as 检索器\n participant Ranker as 排序器\n participant LLM as 大语言模型\n \n Query->>Retriever: 发送查询\n Retriever->>Ranker: 返回 Top-20 候选文档\n Ranker->>LLM: 返回 Top-5 精排文档\n LLM->>Query: 生成答案\n```\n\n---\n\n## 性能优化建议\n\n### 1. 检索器优化\n\n- **调整 Top-K 值**：根据文档库规模和召回需求设置合适的候选数量\n- **选择合适的嵌入模型**：在精度和速度之间权衡\n- **文档分段策略**：合理的分段大小可提升检索效果\n\n### 2. 排序器优化\n\n- **模型选择**：根据精度需求选择合适的排序模型\n- **Top-K 级联**：检索器的 K 值应大于排序器的 K 值（通常 4-10 倍）\n- **批处理**：批量处理可提升排序效率\n\n### 3. 整体策略\n\n| 场景 | 检索器 Top-K | 排序器 Top-K | 预期效果 |\n|------|-------------|-------------|---------|\n| 简单问答 | 10-20 | 3-5 | 快速响应 |\n| 复杂分析 | 50-100 | 5-10 | 高精度 |\n| 大规模检索 | 100-200 | 10-20 | 全面覆盖 |\n\nSources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx) \nSources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)\n\n---\n\n## 最佳实践\n\n1. **先检索后排序**：不要跳过检索阶段直接使用排序器，这会导致性能问题\n2. **模型匹配**：尽量使用与检索器 Embedding 模型兼容的排序器\n3. **监控指标**：关注召回率和精确率，根据业务需求调整参数\n4. **文档预处理**：确保文档格式统一，预处理充分\n\n---\n\n\n\n## Agent 代理系统\n\n### Related Pages\n\nRelated topics: [LLM 生成器](#generators)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)\n- [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)\n- [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)\n- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)\n- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)\n \n\n# Agent 代理系统\n\n## 概述\n\nHaystack Agent 是框架中用于构建智能代理系统的核心组件，它使大型语言模型（LLM）能够通过工具调用、状态管理和多步骤推理来解决复杂任务。Agent 系统将 LLM 与外部工具、数据源和检索系统相结合，实现了自主决策和执行能力。\n\nSources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)\n\n## 架构设计\n\n### 核心组件\n\nAgent 系统由多个核心组件构成，每个组件负责特定的功能职责：\n\n| 组件 | 职责 | 关键特性 |\n|------|------|----------|\n| Agent | 主控制器 | 管理对话循环、决策制定、工具调用 |\n| Tool | 工具接口 | 封装外部功能、参数验证、结果处理 |\n| State | 状态管理 | 维护对话历史、跟踪执行上下文 |\n| Pipeline | 流程编排 | 串联多个组件、定义执行顺序 |\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)\n\n### 组件交互流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent 主控制器]\n B --> C{决策判断}\n C -->|调用工具| D[Tool 执行层]\n C -->|更新状态| E[State 管理层]\n C -->|生成响应| F[最终输出]\n D -->|工具结果| E\n E -->|状态更新| B\n B -->|继续迭代| C\n```\n\n## Agent 核心机制\n\n### 工具调用机制\n\nAgent 通过动态调用外部工具来扩展 LLM 的能力范围。工具可以是：\n\n- **检索工具**：连接向量数据库、执行相似性搜索\n- **API 工具**：调用外部服务、获取实时数据\n- **计算工具**：执行数据处理、格式转换\n- **自定义工具**：用户定义的任意功能\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:1-50)\n\n### 决策循环\n\nAgent 实现了自主决策循环，典型执行流程如下：\n\n```mermaid\ngraph LR\n A[接收任务] --> B[LLM 推理]\n B --> C{需要工具?}\n C -->|是| D[选择工具]\n D --> E[执行工具]\n E --> F[返回结果]\n F --> B\n C -->|否| G[生成回复]\n G --> H[返回用户]\n```\n\n## 状态管理系统\n\n### State 组件\n\nState 是 Agent 系统中负责维护执行状态的关键组件，它记录：\n\n- 对话历史记录\n- 工具调用记录\n- 中间执行结果\n- 上下文变量\n\nSources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)\n\n### 状态数据结构\n\nState 组件使用结构化数据模型来跟踪代理执行过程：\n\n```python\nclass AgentState:\n messages: List[Dict] # 对话历史\n tool_calls: List[Dict] # 工具调用记录\n intermediate_steps: List # 中间步骤\n context: Dict # 上下文变量\n```\n\n### 状态流转图\n\n```mermaid\ngraph TD\n A[初始状态] --> B[消息添加]\n B --> C{执行工具?}\n C -->|是| D[记录工具调用]\n D --> E[保存中间结果]\n E --> F[状态更新]\n F --> B\n C -->|否| G[标记完成]\n G --> H[最终状态]\n F --> H\n```\n\n## 使用示例\n\n### 基本 Agent 配置\n\n```python\nfrom haystack import Agent\n\nagent = Agent(\n tools=[retriever, calculator, web_searcher],\n prompt_template=\"你是一个有帮助的助手\"\n)\n```\n\n### 状态初始化\n\n```python\nfrom haystack.agents import AgentState\n\ninitial_state = AgentState(\n messages=[],\n tool_calls=[],\n context={}\n)\n```\n\nSources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx:1-30)\n\n## 与 Pipeline 集成\n\nAgent 可以作为 Pipeline 的组件进行编排，实现复杂的业务流程：\n\n```mermaid\ngraph LR\n A[用户查询] --> B[检索 Pipeline]\n B --> C[Agent 处理]\n C --> D{需要更多数据?}\n D -->|是| E[调用工具]\n E --> B\n D -->|否| F[生成回答]\n F --> G[返回结果]\n```\n\n### Pipeline 中的 Agent 配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| name | str | Agent 实例名称 |\n| tools | List[Tool] | 可用工具列表 |\n| prompt_template | str | 提示词模板 |\n| max_iterations | int | 最大迭代次数 |\n\nSources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx:1-50)\n\n## 最佳实践\n\n### 工具设计原则\n\n1. **单一职责**：每个工具只完成一个明确的任务\n2. **清晰的输入输出**：定义明确的参数和返回值\n3. **错误处理**：为工具添加适当的异常处理机制\n4. **文档完善**：提供清晰的使用说明和示例\n\n### 状态管理建议\n\n1. **定期清理**：避免状态数据无限增长\n2. **关键节点保存**：在重要步骤记录检查点\n3. **上下文优化**：仅保留必要的上下文信息\n\n## 配置选项\n\n### 核心参数表\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `tools` | [] | 关联的工具列表 |\n| `max_steps` | 10 | 最大执行步数 |\n| `tool_call_limit` | 50 | 工具调用上限 |\n| `streaming` | true | 是否启用流式输出 |\n\nSources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:50-80)\n\n## 相关资源\n\n- [Agent 概念文档](./concepts/agents.mdx)\n- [Agent API 参考](./pipeline-components/agents-1/agent.mdx)\n- [State 组件参考](./pipeline-components/agents-1/state.mdx)\n- [Haystack 官方文档](https://docs.haystack.deepset.ai)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：deepset-ai/haystack\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：deepset-ai/haystack\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# haystack - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 haystack 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Open-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. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Haystack 简介。围绕“Haystack 简介”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. core-concepts：核心概念。围绕“核心概念”模拟一次用户任务，不展示安装或运行结果。\n4. pipeline-system：Pipeline 系统。围绕“Pipeline 系统”模拟一次用户任务，不展示安装或运行结果。\n5. document-stores：文档存储系统。围绕“文档存储系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Haystack 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. core-concepts\n输入：用户提供的“核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. pipeline-system\n输入：用户提供的“Pipeline 系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. document-stores\n输入：用户提供的“文档存储系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Haystack 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / core-concepts：Step 3 必须围绕“核心概念”形成一个小中间产物，并等待用户确认。\n- Step 4 / pipeline-system：Step 4 必须围绕“Pipeline 系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / document-stores：Step 5 必须围绕“文档存储系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/deepset-ai/haystack\n- https://github.com/deepset-ai/haystack#readme\n- README.md\n- VERSION.txt\n- docs-website/docs/overview/installation.mdx\n- docs-website/docs/overview/get-started.mdx\n- docs-website/docs/concepts/concepts-overview.mdx\n- docs-website/docs/concepts/components.mdx\n- docs-website/docs/concepts/pipelines.mdx\n- docs-website/docs/concepts/data-classes.mdx\n- docs-website/docs/concepts/pipelines/creating-pipelines.mdx\n- docs-website/docs/concepts/pipelines/debugging-pipelines.mdx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 haystack 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：deepset-ai/haystack\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install haystack-ai\n```\n\n来源：https://github.com/deepset-ai/haystack#readme\n\n## 来源\n\n- repo: https://github.com/deepset-ai/haystack\n- docs: https://github.com/deepset-ai/haystack#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_2f942674156344b28c4ea6516b388287"
}