{
"canonical_name": "run-llama/llama_index",
"compilation_id": "pack_75035a96b29f4f56a720a90004d12eda",
"created_at": "2026-05-11T07:26:03.724978+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 llama-index-core` 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 llama-index-core",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_7f2a80b6ee624d34a64a3e8151486306"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_780c5e0e6b05fdfe8e4caca210f45bcb",
"canonical_name": "run-llama/llama_index",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/run-llama/llama_index",
"slug": "llama-index",
"source_packet_id": "phit_859d5bab7cf941d5980cf216af9c7986",
"source_validation_id": "dval_9e2ab30b6c4046ec86fff5b1edf66d31"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 7399,
"github_stars": 49374,
"one_liner_en": "LlamaIndex is the leading document agent and OCR platform",
"one_liner_zh": "LlamaIndex is the leading document agent and OCR platform",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "llama_index",
"title_zh": "llama_index 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"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_859d5bab7cf941d5980cf216af9c7986",
"page_model": {
"artifacts": {
"artifact_slug": "llama-index",
"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 llama-index-core",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/run-llama/llama_index#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "LlamaIndex is the leading document agent and OCR platform"
},
{
"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": "Sandbox install result is missing.",
"category": "能力坑",
"evidence": [
"evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing."
],
"severity": "high",
"suggested_check": "优先补证或在页面明确标记为未验证。",
"title": "能力证据存在缺口",
"user_impact": "缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:560704231 | https://github.com/run-llama/llama_index | 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:560704231 | https://github.com/run-llama/llama_index | 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:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | 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:560704231 | https://github.com/run-llama/llama_index | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1933,
"forks": 7399,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 49374,
"open_issues": 351,
"pushed_at": "2026-05-11T20:18:56.000Z"
},
"source_url": "https://github.com/run-llama/llama_index",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "LlamaIndex is the leading document agent and OCR platform",
"title": "llama_index 能力包",
"trial_prompt": "# llama_index - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 llama_index 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LlamaIndex is the leading document agent and OCR platform 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：LlamaIndex 简介。围绕“LlamaIndex 简介”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. system_architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. core_components：核心组件详解。围绕“核心组件详解”模拟一次用户任务，不展示安装或运行结果。\n5. data_ingestion：数据摄取流程。围绕“数据摄取流程”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“LlamaIndex 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system_architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. core_components\n输入：用户提供的“核心组件详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. data_ingestion\n输入：用户提供的“数据摄取流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“LlamaIndex 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system_architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / core_components：Step 4 必须围绕“核心组件详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / data_ingestion：Step 5 必须围绕“数据摄取流程”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/run-llama/llama_index\n- https://github.com/run-llama/llama_index#readme\n- README.md\n- llama-index-core/llama_index/core/__init__.py\n- llama-index-core/README.md\n- docs/examples/vector_stores/SimpleIndexDemo.ipynb\n- docs/src/content/docs/framework/getting_started/installation.mdx\n- docs/src/content/docs/framework/getting_started/starter_example.mdx\n- llama-index-core/llama_index/core/indices/base.py\n- llama-index-core/llama_index/core/query_engine/retriever_query_engine.py\n- llama-index-core/llama_index/core/storage/storage_context.py\n- llama-index-core/llama_index/core/schema.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 llama_index 的核心服务。\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: [Feature Request]: Built-in LLM Failover for Reliability（https://github.com/run-llama/llama_index/issues/19631）；github/github_issue: [Feature Request]: add (detailed) usage info to raw when using Structure（https://github.com/run-llama/llama_index/issues/19845）；github/github_issue: [Bug]: `thinking_delta` not populated on AgentStream events when thinkin（https://github.com/run-llama/llama_index/issues/20349）；github/github_issue: [Bug]: [llama-index-core] async_acquire() in TokenBucketRateLimiter and （https://github.com/run-llama/llama_index/issues/21603）；github/github_issue: [Question]: how to add human-in-the-loop capability to ReActAgent?（https://github.com/run-llama/llama_index/issues/21599）；github/github_issue: Proposal: Agent Threat Rules detection integration for LlamaIndex（https://github.com/run-llama/llama_index/issues/21601）；github/github_issue: Improve developer error message for unrecognized embedding names in `loa（https://github.com/run-llama/llama_index/issues/21597）；github/github_issue: [Bug]: Bedrock Converse streaming produces string `tool_kwargs` in `Tool（https://github.com/run-llama/llama_index/issues/21579）；github/github_issue: [Bug]: Breaking Image/Index node fetching behavior after refactor（https://github.com/run-llama/llama_index/issues/19499）；github/github_issue: [Bug]: PydanticUserError: The `__modify_schema__` method is not supporte（https://github.com/run-llama/llama_index/issues/16540）；github/github_issue: [Bug]: gemini-embedding-2 task instructions not implemented (task_type d（https://github.com/run-llama/llama_index/issues/21535）；github/github_release: v0.14.21（https://github.com/run-llama/llama_index/releases/tag/v0.14.21）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request]: Built-in LLM Failover for Reliability",
"url": "https://github.com/run-llama/llama_index/issues/19631"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request]: add (detailed) usage info to raw when using Structure",
"url": "https://github.com/run-llama/llama_index/issues/19845"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: `thinking_delta` not populated on AgentStream events when thinkin",
"url": "https://github.com/run-llama/llama_index/issues/20349"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: [llama-index-core] async_acquire() in TokenBucketRateLimiter and ",
"url": "https://github.com/run-llama/llama_index/issues/21603"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Question]: how to add human-in-the-loop capability to ReActAgent?",
"url": "https://github.com/run-llama/llama_index/issues/21599"
},
{
"kind": "github_issue",
"source": "github",
"title": "Proposal: Agent Threat Rules detection integration for LlamaIndex",
"url": "https://github.com/run-llama/llama_index/issues/21601"
},
{
"kind": "github_issue",
"source": "github",
"title": "Improve developer error message for unrecognized embedding names in `loa",
"url": "https://github.com/run-llama/llama_index/issues/21597"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Bedrock Converse streaming produces string `tool_kwargs` in `Tool",
"url": "https://github.com/run-llama/llama_index/issues/21579"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Breaking Image/Index node fetching behavior after refactor",
"url": "https://github.com/run-llama/llama_index/issues/19499"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: PydanticUserError: The `__modify_schema__` method is not supporte",
"url": "https://github.com/run-llama/llama_index/issues/16540"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: gemini-embedding-2 task instructions not implemented (task_type d",
"url": "https://github.com/run-llama/llama_index/issues/21535"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.14.21",
"url": "https://github.com/run-llama/llama_index/releases/tag/v0.14.21"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "LlamaIndex is the leading document agent and OCR platform",
"effort": "安装已验证",
"forks": 7377,
"icon": "code",
"name": "llama_index 能力包",
"risk": "可发布",
"slug": "llama-index",
"stars": 49262,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/run-llama/llama_index 项目说明书\n\n生成时间：2026-05-11 04:42:04 UTC\n\n## 目录\n\n- [LlamaIndex 简介](#introduction)\n- [快速入门指南](#quickstart)\n- [系统架构](#system_architecture)\n- [核心组件详解](#core_components)\n- [数据摄取流程](#data_ingestion)\n- [节点解析器](#node_parsing)\n- [存储层架构](#storage_layer)\n- [智能体系统](#agent_system)\n- [工作流引擎](#workflow_engine)\n- [查询引擎](#query_engine)\n\n\n\n## LlamaIndex 简介\n\n### 相关页面\n\n相关主题：[快速入门指南](#quickstart), [系统架构](#system_architecture), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/run-llama/llama_index/blob/main/README.md)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)\n- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n- [llama-index-integrations/llms/llama-index-llms-contextual/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-contextual/README.md)\n- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n \n\n# LlamaIndex 简介\n\n## 概述\n\nLlamaIndex 是一个用于构建 **LLM（大型语言模型）应用** 的数据框架，官方仓库位于 [run-llama/llama_index](https://github.com/run-llama/llama_index)。该框架的核心设计理念是简化 LLM 与私有或特定领域数据的连接过程，使开发者能够快速构建检索增强生成（RAG）系统、问答应用和数据索引工具。\n\nLlamaIndex 提供了丰富的数据连接器（Readers）、索引构建能力、检索和查询引擎，以及与多种 LLM 提供商的无缝集成。资料来源：[README.md:1]()\n\n## 核心架构\n\nLlamaIndex 的整体架构可分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[数据源] --> B[Readers 数据读取层]\n B --> C[Documents 文档对象]\n C --> D[Index 索引层]\n D --> E[Retrievers 检索层]\n E --> F[Query Engine 查询引擎]\n F --> G[LLM 输出层]\n \n B --> B1[Web Readers]\n B --> B2[File Readers]\n B --> B3[API Readers]\n B --> B4[Database Readers]\n \n G --> G1[OpenAI]\n G --> G2[Ollama]\n G --> G3[LM Studio]\n G --> G4[ModelScope]\n```\n\n### 模块层次说明\n\n| 层次 | 功能描述 | 核心组件 |\n|------|----------|----------|\n| **数据读取层** | 从各类数据源加载原始数据 | RemoteDepthReader, DoclingReader, WikipediaReader 等 |\n| **文档对象层** | 将数据转换为标准化的 Document 对象 | Document, MediaResource |\n| **索引层** | 构建可检索的向量或结构化索引 | VectorStoreIndex, SummaryIndex |\n| **检索层** | 根据查询获取相关文档 | Retriever, similarity_top_k 参数 |\n| **查询引擎层** | 执行检索并调用 LLM 生成答案 | QueryEngine, as_query_engine() |\n| **LLM 输出层** | 与各类 LLM 提供商集成 | Contextual, LMStudio, Ollama 等 |\n\n## 核心概念\n\n### Document 文档对象\n\nDocument 是 LlamaIndex 中的核心数据单元，用于表示任意文本或多媒体内容。\n\n```python\nfrom llama_index.core.schema import Document, MediaResource\n\ndoc = Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"这是一段示例文本内容\"\n ),\n)\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:18-25]()\n\n### Index 索引\n\n索引是将文档组织成可高效检索结构的关键组件。最常用的是 VectorStoreIndex，它将文档转换为向量表示进行语义检索。\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\n\nindex = VectaraIndex.from_documents(docs)\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:35]()\n\n## 数据读取器（Readers）\n\nLlamaIndex 提供了丰富的读取器集成，支持从多种数据源加载数据。\n\n### Web 数据读取器\n\n| 读取器名称 | 功能描述 | 依赖库 |\n|-----------|----------|--------|\n| WholeSiteReader | 整站爬取，支持深度递归 | 内置 |\n| NewsArticleReader | 新闻文章解析 | newspaper3k |\n| UnstructuredURLLoader | URL 内容提取 | unstructured |\n| ReadabilityWebPageReader | 网页主内容提取 | readability |\n| MainContentExtractorReader | 主内容提取 | main_content_extractor |\n| TrafilaturaWebReader | 网页内容解析 | trafilatura |\n\n使用示例：\n\n```python\nfrom llama_index.readers.web import NewsArticleReader\n\nreader = NewsArticleReader(use_nlp=False)\ndocuments = reader.load_data(\n urls=[\"https://www.example.com/news/article.html\"]\n)\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md:15-20]()\n\n### 整站爬取功能\n\nWholeSiteReader 支持从指定 URL 开始，按深度递归爬取整个网站的内容：\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:10-20]()\n\n### 文档解析读取器\n\n**Docling Reader** 支持从 PDF、DOCX、HTML 等格式提取内容：\n\n```python\nfrom llama_index.readers.docling import DoclingReader\n\nreader = DoclingReader()\ndocs = reader.load_data(file_path=\"https://arxiv.org/pdf/2408.09869\")\n```\n\n支持的文件格式：\n\n| 格式 | 支持情况 | 导出类型 |\n|------|----------|----------|\n| PDF | ✅ 完整支持 | Markdown / JSON |\n| DOCX | ✅ 完整支持 | Markdown / JSON |\n| HTML | ✅ 完整支持 | Markdown / JSON |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md:15-35]()\n\n### Wikipedia 读取器\n\n```python\nfrom llama_index.readers.wikipedia import WikipediaReader\n\nreader = WikipediaReader()\ndocuments = reader.load_data(pages=[\"Page Title 1\", \"Page Title 2\"])\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-wikipedia/README.md:20-30]()\n\n## LLM 集成\n\n### 主要 LLM 提供商\n\n| 提供商 | 包名 | 特点 |\n|--------|------|------|\n| Contextual | llama-index-llms-contextual | 上下文感知的 LLM |\n| LM Studio | llama-index-llms-lmstudio | 本地模型服务 |\n| ModelScope | llama-index-llms-modelscope | 阿里魔搭模型 |\n| Ollama | 内置支持 | 本地 LLM 运行 |\n\n### Contextual LLM 示例\n\n```python\nfrom llama_index.llms.contextual import Contextual\n\nllm = Contextual(model=\"contextual-clm\", api_key=\"your_api_key\")\nresponse = llm.complete(\"Explain the importance of Grounded Language Models.\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-contextual/README.md:15-20]()\n\n### LM Studio 集成\n\n```python\nfrom llama_index.llms.lmstudio import LMStudio\n\nllm = LMStudio(\n model_name=\"Hermes-2-Pro-Llama-3-8B\",\n base_url=\"http://localhost:1234/v1\",\n temperature=0.7,\n)\n\nmessages = [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=\"You are an expert AI assistant.\",\n ),\n ChatMessage(\n role=MessageRole.USER,\n content=\"What is the significance of the number 42?\",\n ),\n]\n\nresponse = llm.chat(messages=messages)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-lmstudio/README.md:15-35]()\n\n## 向量嵌入集成\n\n### Ollama 嵌入模型\n\nOllama 提供了多个嵌入模型选项：\n\n| 模型名称 | 用途 | 特点 |\n|----------|------|------|\n| nomic-embed-text | 通用嵌入 | 通用目的 |\n| embeddinggemma | 文本嵌入 | Google Gemma 系列 |\n| mxbai-embed-large | 高质量嵌入 | 大规模模型 |\n\n安装与使用：\n\n```bash\nollama pull nomic-embed-text\n```\n\n```python\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://localhost:11434\",\n)\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:5-30]()\n\n### ModelScope 嵌入\n\n```python\nfrom llama_index.embeddings.modelscope.base import ModelScopeEmbedding\n\nmodel = ModelScopeEmbedding(\n model_name=\"iic/nlp_gte_sentence-embedding_chinese-base\",\n model_revision=\"master\",\n)\n\nrsp = model.get_query_embedding(\"你好，你是谁？\")\nrsp = model.get_text_embedding_batch([\"你好\", \"我是学生\"])\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md:15-35]()\n\n## 检索与查询流程\n\n### 标准 RAG 工作流\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Query Engine]\n B --> C[Retriever 检索]\n C --> D[向量相似度匹配]\n D --> E[相关文档]\n E --> F[LLM 生成]\n F --> G[最终回答]\n```\n\n### 检索器使用\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\n\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"How will users feel about this new tool?\")\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:45-50]()\n\n### 查询引擎使用\n\n```python\nquery_engine = index.as_query_engine()\nresults = query_engine.query(\"用户对工具的感受如何？\")\n```\n\n## 完整使用示例\n\n以下是一个典型的 LlamaIndex 完整使用流程：\n\n```mermaid\ngraph TD\n A[加载数据] --> B[创建索引]\n B --> C[获取检索器]\n C --> D{使用方式}\n D -->|直接检索| E[Retriever]\n D -->|生成回答| F[Query Engine]\n E --> G[相关文档列表]\n F --> H[LLM 回答]\n```\n\n完整代码示例：\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.web import NewsArticleReader\n\n# 1. 加载数据\nreader = NewsArticleReader(use_nlp=False)\ndocuments = reader.load_data(urls=[\"https://example.com/article.html\"])\n\n# 2. 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 3. 获取检索器\nretriever = index.as_retriever(similarity_top_k=5)\n\n# 4. 检索相关文档\nresults = retriever.retrieve(\"查询内容\")\n\n# 或使用查询引擎获取 LLM 回答\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"查询内容\")\n```\n\n## 特性总结\n\n### LlamaIndex 核心能力矩阵\n\n| 能力维度 | 支持情况 | 说明 |\n|----------|----------|------|\n| 多数据源接入 | ✅ | Web、文件、API、数据库等 |\n| 多格式文档解析 | ✅ | PDF、DOCX、HTML、Markdown 等 |\n| 多种 LLM 集成 | ✅ | OpenAI、Ollama、LM Studio 等 |\n| 向量嵌入支持 | ✅ | 本地模型、云服务多种选择 |\n| RAG 检索增强 | ✅ | 内置检索和查询引擎 |\n| 可扩展架构 | ✅ | 模块化设计，支持自定义组件 |\n\n## 引用信息\n\n如需在学术论文中引用 LlamaIndex，请使用以下格式：\n\n```\n@software{Liu_LlamaIndex_2022,\nauthor = {Liu, Jerry},\ndoi = {10.5281/zenodo.1234},\nmonth = {11},\ntitle = {{LlamaIndex}},\nurl = {https://github.com/jerryjliu/llama_index},\nyear = {2022}\n}\n```\n\n资料来源：[README.md:95-102]()\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[LlamaIndex 简介](#introduction), [系统架构](#system_architecture), [数据摄取流程](#data_ingestion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md)\n- [llama-index-integrations/llms/llama-index-llms-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-ollama/README.md)\n- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n- [llama-index-integrations/llms/llama-index-llms-konko/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-konko/README.md)\n \n\n# 快速入门指南\n\n## 概述\n\nLlamaIndex 是一个强大的大语言模型（LLM）数据框架，旨在帮助开发者构建基于私有知识和增强语言模型的应用程序。本指南将引导您从零开始，快速掌握 LlamaIndex 的核心功能和使用方法。\n\nLlamaIndex 的主要应用场景包括：\n\n- **文档问答系统**：基于私有文档库构建智能问答应用\n- **语义搜索**：使用向量数据库实现高效的信息检索\n- **代理（Agent）应用**：构建能够访问多种工具的 AI 代理\n- **数据摄取与索引**：支持从多种数据源加载和索引文档\n\n## 安装\n\n### 基本安装\n\n使用 pip 安装 LlamaIndex 核心包：\n\n```bash\npip install llama-index\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()\n\n### 集成包安装\n\n根据您的具体需求，可以安装不同的集成包：\n\n| 集成类型 | 包名称 | 用途 |\n|---------|--------|------|\n| Web 读取器 | `llama-index-readers-web` | 从网页加载内容 |\n| Ollama LLM | `llama-index-llms-ollama` | 本地 LLM 支持 |\n| Ollama 嵌入 | `llama-index-embeddings-ollama` | 本地嵌入模型 |\n| Vectara 索引 | `llama-index-indices-managed-vectara` | Vectara 云索引 |\n| Konko LLM | `llama-index-llms-konko` | Konko API 支持 |\n| LangChain 集成 | 随上述包自动安装 | 与 LangChain 代理集成 |\n\n安装示例：\n\n```bash\npip install llama-index-llms-ollama\npip install llama-index-readers-web\npip install llama-index-indices-managed-vectara\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n## 核心概念\n\n### 数据流程架构\n\n```mermaid\ngraph TD\n A[数据源] --> B[Document 文档]\n B --> C[Node 节点]\n C --> D[Index 索引]\n D --> E[Retriever 检索器]\n E --> F[Query Engine 查询引擎]\n F --> G[Response 响应]\n \n H[LLM] --> F\n```\n\nLlamaIndex 的核心数据流程包含以下关键组件：\n\n1. **Document（文档）**：表示要索引的原始数据，可以是文本、HTML、PDF 等格式\n2. **Node（节点）**：将 Document 分割后的数据块，便于高效检索\n3. **Index（索引）**：存储节点的数据结构，支持快速相似度搜索\n4. **Retriever（检索器）**：从索引中获取相关节点\n5. **Query Engine（查询引擎）**：整合检索和 LLM 生成答案\n\n### 文档加载\n\nLlamaIndex 支持多种数据源加载器：\n\n| 加载器 | 包名 | 数据源 |\n|-------|------|--------|\n| SimpleDirectoryReader | 核心包 | 本地文件系统 |\n| WholeSiteReader | llama-index-readers-web | 整个网站 |\n| ReadabilityWebPageReader | llama-index-readers-web | 单个网页（可读性优化） |\n| NewsArticleReader | llama-index-readers-web | 新闻文章 |\n| RemoteDepthReader | llama-index-readers-remote-depth | 远程 URL 层级 |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()\n\n## 快速示例\n\n### 基础文档问答\n\n以下示例展示如何使用 LlamaIndex 构建最基本的文档问答系统：\n\n```python\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\n# 加载本地文档\ndocuments = SimpleDirectoryReader(\"data\").load_data()\n\n# 创建向量索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 创建查询引擎\nquery_engine = index.as_query_engine()\n\n# 执行查询\nresponse = query_engine.query(\"作者在成长过程中做了些什么？\")\nprint(response)\n```\n\n这是 LlamaIndex 最基本的用法模式：加载文档 → 创建索引 → 查询。\n\n### 使用 Web 读取器\n\n#### 单页面读取\n\n```python\nfrom llama_index.readers.web import ReadabilityWebPageReader\n\nloader = ReadabilityWebPageReader()\ndocuments = loader.load_data(\n url=\"https://example.com/article\"\n)\n\nindex = VectorStoreIndex.from_documents(documents)\nprint(index.query(\"这篇文文章的主要内容是什么？\"))\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()\n\n#### 全站抓取\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\n# 初始化抓取器\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\n# 从基础 URL 开始抓取\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n\nindex = VectorStoreIndex.from_documents(documents)\nindex.query(\"这个网站使用什么语言？\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()\n\n### 使用本地 LLM（Ollama）\n\n```python\nfrom llama_index.llms.ollama import Ollama\n\n# 初始化 Ollama LLM\nllm = Ollama(model=\"llama3.1:latest\", request_timeout=120.0)\n\n# 生成补全\nresp = llm.complete(\"Paul Graham 是谁？\")\nprint(resp)\n\n# 使用聊天接口\nfrom llama_index.core.llms import ChatMessage\n\nmessages = [\n ChatMessage(\n role=\"system\", \n content=\"你是一个友好的助手\"\n ),\n ChatMessage(\n role=\"user\", \n content=\"解释一下大爆炸理论\"\n ),\n]\n\nresp = llm.chat(messages)\nprint(resp)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n### 使用云索引服务（Vectara）\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\nfrom llama_index.core.schema import Document, MediaResource\nimport os\n\n# 设置环境变量\nos.environ[\"VECTARA_API_KEY\"] = \"\"\nos.environ[\"VECTARA_CORPUS_KEY\"] = \"\"\n\n# 创建文档\ndocs = [\n Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"这是 Vectara 与 LlamaIndex 集成的测试文本。\"\n ),\n ),\n]\n\n# 创建索引并添加文档\nindex = VectaraIndex.from_documents(docs)\n\n# 检索文档\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"用户体验如何？\")\nprint(results[0])\n\n# 作为查询引擎使用\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"总结主要内容\")\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()\n\n## 与 LangChain 集成\n\nLlamaIndex 可以作为工具集成到 LangChain 代理中：\n\n```python\nfrom llama_index.core import VectorStoreIndex, download_loader\nfrom langchain.agents import initialize_agent, Tool\nfrom langchain.llms import OpenAI\nfrom langchain.chains.conversation.memory import ConversationBufferMemory\n\nfrom llama_index.readers.web import ReadabilityWebPageReader\n\n# 加载文档\nloader = ReadabilityWebPageReader()\ndocuments = loader.load_data(\n url=\"https://example.com/article\"\n)\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 定义工具\ntools = [\n Tool(\n name=\"Website Index\",\n func=lambda q: index.query(q),\n description=\"用于回答网站内容相关问题的工具。\",\n ),\n]\n\n# 初始化代理\nllm = OpenAI(temperature=0)\nmemory = ConversationBufferMemory(memory_key=\"chat_history\")\nagent_chain = initialize_agent(\n tools, llm, agent=\"zero-shot-react-description\", memory=memory\n)\n\n# 运行代理\noutput = agent_chain.run(input=\"网站的主要内容是什么？\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()\n\n## 嵌入模型配置\n\n### Ollama 嵌入\n\n```python\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://your-remote-server:11434\",\n)\n\n# 使用嵌入模型\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\ndocuments = SimpleDirectoryReader(\"data\").load_data()\nindex = VectorStoreIndex.from_documents(documents, embed_model=embed_model)\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()\n\n### 可用嵌入模型\n\n| 模型 ID | 描述 | 适用场景 |\n|--------|------|---------|\n| `nomic-embed-text` | 通用嵌入模型 | 通用任务 |\n| `embeddinggemma` | Google Gemma 系列 | 高精度需求 |\n| `mxbai-embed-large` | 大型嵌入模型 | 最佳质量 |\n\n安装嵌入模型：\n\n```bash\nollama pull nomic-embed-text\n```\n\n## 完整 RAG 流程\n\n```mermaid\ngraph LR\n A[用户问题] --> B[检索]\n B --> C[向量相似度匹配]\n C --> D[相关文档片段]\n D --> E[上下文构建]\n E --> F[LLM 生成]\n F --> G[最终回答]\n \n H[(文档库)] --> I[文档加载]\n I --> J[分块处理]\n J --> K[向量编码]\n K --> C\n```\n\n完整的 RAG（检索增强生成）流程包括：\n\n| 阶段 | 组件 | 描述 |\n|-----|------|------|\n| 数据摄入 | Document Loader | 从各种来源加载文档 |\n| 处理 | Node Parser | 将文档分割成小块 |\n| 索引 | Vector Store | 存储向量表示 |\n| 检索 | Retriever | 找到相关上下文 |\n| 生成 | Query Engine + LLM | 生成最终答案 |\n\n## 常见问题\n\n### 连接错误\n\n如果遇到连接错误，请检查：\n\n1. Ollama 服务是否运行：`ollama serve`\n2. `base_url` 是否与 Ollama 服务器地址匹配\n3. 模型是否已下载：`ollama pull `\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()\n\n### 模型未找到\n\n如果出现\"模型未找到\"错误：\n\n1. 列出可用模型：`ollama list`\n2. 拉取所需模型：`ollama pull `\n3. 确认模型名称在代码中完全匹配\n\n### 超时配置\n\n默认超时时间为 30 秒，可以通过 `request_timeout` 参数调整：\n\n```python\nllm = Ollama(\n model=\"llama3.1:latest\", \n request_timeout=300.0\n)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n## 下一步\n\n掌握基础用法后，您可以深入学习以下高级主题：\n\n- **自定义检索器**：实现混合搜索策略\n- **流式响应**：实现实时生成输出\n- **回调系统**：集成 Argilla 等监控工具\n- **多模态支持**：处理图像和文本混合内容\n- **代理工具集成**：构建更复杂的 AI 代理应用\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件详解](#core_components), [数据摄取流程](#data_ingestion), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/indices/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/base.py)\n- [llama-index-core/llama_index/core/query_engine/retriever_query_engine.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py)\n- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md)\n- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n \n\n# 系统架构\n\n## 概述\n\nLlamaIndex 是一个专为大型语言模型（LLM）应用设计的检索增强生成（RAG）框架，其系统架构围绕数据索引构建、智能查询处理和持久化存储三大核心功能展开。框架采用模块化设计，通过清晰的分层结构将数据加载、文档处理、索引管理、查询执行和存储管理解耦，同时保持各组件间的无缝协作能力。\n\nLlamaIndex 的架构设计遵循\"数据优先\"的原则，首先通过多元化的 Reader 组件从不同数据源提取内容，然后经过解析和分块处理形成结构化的 Node 对象，最终由各类 Index 索引进行组织和存储。查询阶段则通过 Query Engine 实现语义理解和信息检索的结合，为 LLM 提供准确的上下文支撑。\n\n## 核心架构组件\n\n### 索引层（Indices）\n\n索引层是 LlamaIndex 架构的核心，负责将非结构化数据转换为可高效检索的向量表示。根据应用场景的不同，框架提供了多种索引类型的实现：\n\n| 索引类型 | 用途描述 | 适用场景 |\n|---------|---------|----------|\n| VectorStoreIndex | 基于向量嵌入的语义检索 | 问答系统、内容推荐 |\n| DocumentSummaryIndex | 文档摘要索引 | 长文档快速概览 |\n| KnowledgeGraphIndex | 知识图谱索引 | 关系型问答、实体链接 |\n| TreeIndex | 树形结构索引 | 分层文档组织 |\n| KeywordTableIndex | 关键词表索引 | 精确关键词匹配 |\n\n索引架构采用基类继承设计，所有索引类型都继承自 BaseIndex 抽象基类，共享通用的索引生命周期管理接口，包括索引创建、更新、删除和持久化等核心操作。这种设计确保了索引行为的一致性，同时允许各子类根据具体需求实现特定的索引逻辑。\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[Node Parser 节点解析器]\n B --> C[Index 索引构建]\n C --> D[VectorStoreIndex 向量索引]\n C --> E[KnowledgeGraphIndex 知识图谱索引]\n C --> F[TreeIndex 树形索引]\n D --> G[Vector Store 向量存储]\n E --> H[Graph Store 图存储]\n F --> I[Document Store 文档存储]\n```\n\n资料来源：[llama-index-core/llama_index/core/indices/base.py:1-50]()\n\n### 查询引擎层（Query Engine）\n\n查询引擎层负责接收用户查询并返回相关结果。框架提供了多种查询引擎实现，其中 RetrieverQueryEngine 是最常用的实现，它将检索器（Retriever）与 LLM 相结合，实现语义理解与信息检索的闭环处理。\n\nRetrieverQueryEngine 的核心工作流程包括：首先接收自然语言查询，然后调用底层的 Retriever 从索引中检索相关节点，接着将检索结果与原始查询组装为 Prompt 提交给 LLM 进行答案生成。这种设计实现了检索与生成的分离，使得用户可以灵活切换不同的检索策略和 LLM 模型。\n\n```mermaid\ngraph LR\n A[User Query 用户查询] --> B[Retriever 检索器]\n B --> C[Retrieved Nodes 检索节点]\n C --> D[Response Synthesizer 响应合成器]\n D --> E[LLM 大语言模型]\n E --> F[Final Response 最终响应]\n```\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py:1-80]()\n\n### 存储层（Storage）\n\n存储层负责管理索引数据和文档的持久化。StorageContext 是存储架构的核心抽象，它整合了三种存储组件：DocStore（文档存储）、IndexStore（索引存储）和 VectorStore（向量存储）。这种三分层设计使得不同类型的数据可以选用最适合的存储后端。\n\n| 存储组件 | 存储内容 | 支持的后端 |\n|---------|---------|------------|\n| DocStore | 原始文档和节点数据 | MongoDB、Redis、SimpleDocumentStore |\n| IndexStore | 索引元数据 | MongoDB、Redis、SimpleIndexStore |\n| VectorStore | 向量嵌入数据 | Chroma、Pinecone、Weaviate、Milvus |\n\nStorageContext 提供了统一的存储接口抽象，屏蔽了底层存储实现细节，使得应用程序可以在不同存储后端之间灵活切换而无需修改业务逻辑代码。\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py:1-100]()\n\n## 数据加载与处理\n\n### Reader 集成系统\n\nLlamaIndex 的 Reader 系统提供了从多样化数据源加载内容的能力，这是实现端到端 RAG 流程的数据入口。Reader 架构采用统一接口设计，所有 Reader 都实现 BaseReader 接口，提供标准化的 `load_data()` 方法。\n\n当前框架支持的主要 Reader 类型及其数据源：\n\n| Reader 类型 | 数据源 | 用途 |\n|------------|--------|------|\n| NewsArticleReader | 新闻网站 | 抓取 CNBC、The Verge 等新闻内容 |\n| TrafilaturaWebReader | 通用网页 | 使用 trafilatura 库提取网页正文 |\n| MainContentExtractorReader | 静态网站 | 提取网页主要内容区域 |\n| UnstructuredURLLoader | 任意网页 | 使用 Unstructured.io 解析 HTML |\n| ReadabilityWebPageReader | 新闻文章 | 使用 Mozilla Readability 算法 |\n| WholeSiteReader | 整站爬取 | 按深度递归爬取整个网站 |\n| WikipediaReader | Wikipedia | 读取 Wikipedia 条目内容 |\n| SemanticScholarReader | 学术论文 | 获取 Semantic Scholar 论文数据 |\n| DoclingReader | PDF/DOCX/HTML | 使用 Docling 提取复杂文档 |\n| BoxReader | Box 云存储 | 读取 Box 中的文件和文件夹 |\n| WordPressReader | WordPress 博客 | 通过 WP REST API 获取内容 |\n\n这种多元化的 Reader 设计确保了 LlamaIndex 可以接入几乎所有常见的数据源，从网页内容到企业文档，从学术论文到云存储文件，构建完整的 RAG 数据管道。\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md]()\n资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md]()\n\n### 文档处理流程\n\n文档从原始数据到可索引状态的转换过程涉及多个处理阶段：\n\n```mermaid\ngraph TD\n A[Raw Data 原始数据] --> B[Reader 读取器]\n B --> C[Document 对象]\n C --> D[Node Parser 节点解析器]\n D --> E[TextNode / ImageNode]\n E --> F[Embedding Model 嵌入模型]\n F --> G[Indexed Nodes 索引节点]\n G --> H[VectorStoreIndex]\n```\n\nNode Parser 负责将 Document 拆分为更小的语义单元（Node），这个过程支持多种策略：\n\n- **TokenTextSplitter**：基于 token 数量的文本分块\n- **SentenceSplitter**：基于句子边界的分块\n- **RecursiveCharacterTextSplitter**：递归字符分块，优先保持段落完整性\n\n## 查询处理流程\n\n### 检索与生成分离\n\nLlamaIndex 架构的核心设计理念之一是检索与生成的分离。这种设计带来了多重优势：首先，允许独立优化检索和生成两个环节；其次，支持多种检索策略的灵活组合；第三，便于实现缓存和结果复用。\n\n```mermaid\ngraph TD\n A[Query 输入查询] --> B[Query Transform 查询变换]\n B --> C[Embedding 嵌入生成]\n C --> D[Vector Search 向量搜索]\n D --> E[Top-K Retrieval Top-K 检索]\n E --> F[Node Postprocessors 节点后处理器]\n F --> G[Context Assembly 上下文组装]\n G --> H[LLM Response Generation LLM 响应生成]\n H --> I[Response 输出响应]\n```\n\n### 查询引擎类型\n\n| 引擎类型 | 描述 | 核心特性 |\n|---------|------|----------|\n| RetrieverQueryEngine | 标准检索引擎 | 基础 RAG 流程 |\n| CitationQueryEngine | 引用查询引擎 | 支持答案溯源 |\n| MultiStepQueryEngine | 多步查询引擎 | 处理复杂多跳问题 |\n| SubQuestionQueryEngine | 子问题引擎 | 将复杂问题分解 |\n\nCitationQueryEngine 是一个重要的扩展，它不仅返回答案，还提供答案引用的来源信息，使得用户可以验证和追溯生成内容的准确性。这对于构建可信赖的 RAG 应用至关重要。\n\n## 嵌入与向量化\n\n### 嵌入模型集成\n\nLlamaIndex 的嵌入系统采用插件化设计，通过抽象的 BaseEmbedding 接口支持多种嵌入模型后端。当前支持的嵌入服务包括：\n\n- **OpenAI Embeddings**：OpenAI 的 text-embedding-ada-002 等模型\n- **Ollama Embeddings**：本地运行的 Ollama 模型，如 nomic-embed-text\n- **ModelScope Embeddings**：阿里魔搭平台的嵌入模型，如 nlp_gte_sentence-embedding_chinese-base\n- **HuggingFace Embeddings**：HuggingFace 生态的各种嵌入模型\n\n这种模块化设计允许开发者根据数据语言、应用场景和性能要求选择最合适的嵌入模型，同时保持上层索引和查询逻辑的稳定性。\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md]()\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md]()\n\n## 服务架构\n\n### 服务上下文（ServiceContext）\n\nServiceContext 是 LlamaIndex 的服务配置中心，它聚合了 LLM、嵌入模型、提示模板、回调处理器等运行时组件。通过 ServiceContext，开发者可以一次性配置好整个 RAG 流程所需的全部服务组件。\n\n```mermaid\ngraph TD\n A[ServiceContext] --> B[LLM 大语言模型]\n A --> C[Embedding Model 嵌入模型]\n A --> D[Node Parser 节点解析器]\n A --> E[Prompt Template 提示模板]\n A --> F[Callback Manager 回调管理器]\n G[Query Pipeline] --> A\n H[Index Construction] --> A\n```\n\n### 回调系统\n\nLlamaIndex 提供了全面的回调机制（Callback System），覆盖索引构建、查询执行、检索过程等关键节点。通过 CallbackManager，应用可以：\n\n- 记录执行时间消耗\n- 追踪 Token 使用量\n- 监控检索结果质量\n- 集成第三方监控服务\n\n## 工作流示意\n\n### 端到端 RAG 流程\n\n```mermaid\ngraph LR\n A[数据源] -->|Reader| B[Documents]\n B -->|Node Parser| C[Nodes]\n C -->|Embedding| D[Vector Index]\n D -->|Storage| E[Persist Storage]\n \n F[User Query] -->|Embedding| G[Retrieve]\n G -->|Top-K| H[Relevant Nodes]\n H -->|Context| I[LLM]\n I -->|Generate| J[Response]\n```\n\n## 扩展集成\n\n### 工具系统（Tools）\n\nLlamaIndex 的工具系统允许将索引和查询能力封装为可被 Agent 调用的工具。通过 Tool 接口，开发者可以创建自定义工具，暴露给 LangChain 等 Agent 框架使用。例如，Moss 工具提供了向量搜索能力，支持混合搜索（关键词 + 语义）和可配置的排名参数。\n\n| 工具名称 | 功能描述 | 关键参数 |\n|---------|---------|----------|\n| Moss | 混合向量搜索 | top_k, alpha, model_id |\n| Brightdata | 网络数据采集 | search_engine, web_data_feed |\n| Wikipedia | 维基百科查询 | pages |\n\n### 外部服务集成\n\nLlamaIndex 与多种外部服务保持深度集成，包括向量数据库（Chroma、Milvus、Pinecone）、云存储（Box、S3）、搜索服务（Brightdata）等。这种集成通过统一抽象层实现，确保了核心架构的稳定性同时提供了丰富的生态扩展能力。\n\n## 总结\n\nLlamaIndex 的系统架构体现了现代 LLM 应用框架的设计原则：**模块化、可扩展、关注点分离**。从数据加载到索引构建，从查询处理到响应生成，每个环节都被设计为可独立配置和替换的组件。这种架构使得开发者可以灵活应对不同的应用场景需求，同时享受框架提供的开箱即用功能。随着生态系统的持续发展，LlamaIndex 正在成为构建生产级 RAG 应用的首选框架之一。\n\n---\n\n\n\n## 核心组件详解\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [存储层架构](#storage_layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/schema.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/schema.py)\n- [llama-index-core/llama_index/core/indices/vector_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)\n- [llama-index-core/llama_index/core/indices/property_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/property_graph/base.py)\n- [llama-index-core/llama_index/core/indices/knowledge_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/knowledge_graph/base.py)\n- [llama-index-core/llama_index/core/response_synthesizers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/response_synthesizers/base.py)\n \n\n# 核心组件详解\n\n## 概述\n\nLlamaIndex 是一个强大的大语言模型应用框架，其核心组件构成了构建高级检索增强生成（RAG）系统的基础设施。本文档深入剖析 LlamaIndex 的核心组件体系，包括数据模型、索引类型、检索引擎和响应合成器等关键模块。这些组件协同工作，为开发者提供了从文档处理到智能问答的完整技术栈。\n\nLlamaIndex 的设计理念强调模块化和可扩展性，每个核心组件都遵循统一的接口规范，使得开发者能够灵活地组合和定制系统行为。核心组件之间的关系可以用下图表示：\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[Node 节点]\n B --> C[BaseIndex 索引基类]\n C --> D[VectorStoreIndex 向量索引]\n C --> E[PropertyGraphIndex 属性图索引]\n C --> F[KnowledgeGraphIndex 知识图谱索引]\n D --> G[Retriever 检索器]\n E --> G\n F --> G\n G --> H[ResponseSynthesizer 响应合成器]\n H --> I[Response 响应]\n```\n\n## 数据模型体系\n\n### Document 文档类\n\nDocument 是 LlamaIndex 中表示文档数据的基础单元，封装了原始文本内容和元数据信息。每个 Document 对象包含文本资源和关联的元数据字典，支持灵活的数据存储和检索需求。\n\n```mermaid\nclassDiagram\n class Document {\n +id_: str\n +text_resource: TextResource\n +metadata: Dict[str, Any]\n +embedding: Optional[List[float]]\n +embedding_strategy: Optional[EmbeddingStrategy]\n +__init__(...)\n +to_langchain_document(): langchain Document\n +to_openai_message(): Dict\n +get_content(metadata_mode: MetadataMode): str\n }\n \n class TextResource {\n +text: Optional[str]\n +relationships: Optional[Dict[RelationshipType, List[str]]]\n }\n \n Document *-- TextResource\n```\n\nDocument 类提供了丰富的属性和方法，支持与外部系统（如 LangChain）的无缝集成。text_resource 属性采用组合模式，包含实际文本内容和关系信息。metadata 字典允许存储任意键值对形式的元数据，便于后续检索和过滤。\n\n文档的创建和使用示例：\n\n```python\nfrom llama_index.core.schema import Document, TextResource, MediaResource\n\n# 基础文档创建\ndoc = Document(\n id_=\"doc-001\",\n text_resource=MediaResource(text=\"这是文档的文本内容\"),\n metadata={\"source\": \"example.txt\", \"author\": \"张三\"}\n)\n\n# 获取文档内容\ncontent = doc.get_content(metadata_mode=MetadataMode.ALL)\n```\n\n### Node 节点类\n\nNode 是 Document 的细粒度表示，代表文档经过分块处理后的最小语义单元。Node 继承自 Document，并增加了关联关系和位置信息，用于维护文档结构的层级关系。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id_` | str | 节点唯一标识符 |\n| `text_resource` | TextResource | 文本资源对象 |\n| `metadata` | Dict[str, Any] | 元数据字典 |\n| `relationships` | Dict[RelationshipType, NodeRelationship] | 关联关系映射 |\n| `metadata_seperator` | str | 元数据分隔符 |\n\nNode 的关系类型通过 RelationshipType 枚举定义，主要包括：\n\n- `SOURCE`：指向源文档的关系\n- `PREVIOUS`：指向前一个兄弟节点\n- `NEXT`：指向后一个兄弟节点\n- `PARENT`：指向父节点\n- `CHILD`：指向子节点列表\n\n```python\nfrom llama_index.core.schema import NodeRelationship, RelatedNode\n\n# 创建具有父子关系的节点\nchild_node = TextNode(\n text=\"子节点内容\",\n relationships={\n NodeRelationship.PARENT: RelatedNode(node_id=\"parent-node-id\")\n }\n)\n```\n\n## 索引系统\n\n### VectorStoreIndex 向量存储索引\n\nVectorStoreIndex 是 LlamaIndex 最核心的索引实现，基于向量相似度检索实现高效的语义搜索功能。该索引将文档转换为向量表示，并存储在向量数据库中，支持大规模数据的快速相似度查询。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[QueryEngine 查询引擎]\n B --> C[Retriever 检索器]\n C --> D[BaseRetriever 基类]\n D --> E[VectorRetriever 向量检索器]\n E --> F[VectorStore 向量存储]\n F --> G[相似向量节点]\n G --> H[ResponseSynthesizer]\n H --> I[最终响应]\n \n style F fill:#e1f5fe\n style E fill:#fff3e0\n```\n\nVectorStoreIndex 的核心架构包含以下层次：\n\n#### 索引构建流程\n\n索引的构建过程涉及文档解析、节点分割、向量计算和存储等步骤。以下是索引创建的标准流程：\n\n```python\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\n# 加载文档\ndocuments = SimpleDirectoryReader(\"./data\").load_data()\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 获取查询引擎\nquery_engine = index.as_query_engine()\n\n# 执行查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n#### 向量检索器配置\n\nVectorStoreIndex 提供了丰富的检索配置选项，开发者可以根据具体需求调整检索行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vector_store` | BasePydanticVectorStore | SimpleVectorStore | 向量存储后端 |\n| `embed_model` | BaseEmbedding | None | 嵌入模型 |\n| `llm` | Optional[LLM] | None | 大语言模型 |\n| `similarity_top_k` | int | 1 | 返回的最相似结果数量 |\n| `vector_store_kwargs` | Dict | {} | 向量存储额外参数 |\n\n```python\nfrom llama_index.core.vector_stores import PineconeVectorStore\nfrom llama_index.core import VectorStoreIndex\n\n# 使用自定义向量存储\nvector_store = PineconeVectorStore(\n pinecone_index=pinecone_index,\n embed_model=embed_model\n)\n\nindex = VectorStoreIndex.from_documents(\n documents,\n vector_store=vector_store\n)\n```\n\n#### 检索模式\n\nVectorStoreIndex 支持多种检索模式，通过 as_retriever 方法可以灵活配置：\n\n```python\n# 获取默认检索器\nretriever = index.as_retriever()\n\n# 配置检索参数\nretriever = index.as_retriever(\n vector_store_kwargs={\n \"filter\": {\"category\": \"技术文档\"},\n \"top_k\": 10\n }\n)\n```\n\n### PropertyGraphIndex 属性图索引\n\nPropertyGraphIndex 是 LlamaIndex 提供的图结构索引实现，支持构建和维护复杂的实体关系网络。与传统的平面向量索引不同，PropertyGraphIndex 能够表达实体之间的多层次语义关系。\n\n```mermaid\ngraph LR\n A[实体: LlamaIndex] -->|类型| B[框架]\n A -->|用于| C[构建]\n C -->|对象| D[RAG应用]\n E[实体: RAG] -->|代表| F[检索增强生成]\n \n style A fill:#c8e6c9\n style E fill:#c8e6c9\n style C fill:#fff9c4\n style D fill:#bbdefb\n```\n\n#### 属性图的核心概念\n\nPropertyGraphIndex 基于三元组模型表示知识，三元组由源实体、关系类型和目标实体组成。这种表示方式能够清晰地捕捉现实世界中的复杂语义关联。\n\n核心组件包括：\n\n- **Entities（实体）**：表示现实世界中的对象或概念\n- **Relations（关系）**：表示实体之间的语义关联\n- **Properties（属性）**：为实体和关系添加额外描述信息\n\n#### 创建属性图索引\n\n```python\nfrom llama_index.core.indices.property_graph import PropertyGraphIndex\n\n# 使用 LLM 从文档中提取知识图谱\nindex = PropertyGraphIndex.from_documents(\n documents,\n llm=llm,\n embed_model=embed_model\n)\n\n# 自定义关系和实体提取器\nfrom llama_index.core.indices.property_graph import SchemaLLMPathExtractor\n\nschema_extractor = SchemaLLMPathExtractor(\n llm=llm,\n schema=[\n {\"name\": \"PERSON\", \"props\": [\"name\", \"age\"]},\n {\"name\": \"ORGANIZATION\", \"props\": [\"name\", \"founded\"]}\n ]\n)\n\nindex = PropertyGraphIndex.from_documents(\n documents,\n kg_extractors=[schema_extractor]\n)\n```\n\n### KnowledgeGraphIndex 知识图谱索引\n\nKnowledgeGraphIndex 是专门用于构建知识图谱的索引类型，它利用 LLM 从非结构化文本中提取实体和关系，构建可查询的知识网络。该索引继承自 PropertyGraphIndex，提供了更高级别的抽象和更便捷的 API。\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[LLM 提取器]\n B --> C[三元组抽取]\n C --> D[Entity 实体]\n C --> E[Relation 关系]\n D --> F[知识图谱存储]\n E --> F\n F --> G[检索与查询]\n \n style F fill:#f3e5f5\n```\n\n#### 知识图谱索引配置\n\nKnowledgeGraphIndex 提供了丰富的配置选项：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `storage_context` | StorageContext | 存储上下文 |\n| `llm` | LLM | 用于抽取的大语言模型 |\n| `embed_model` | BaseEmbedding | 嵌入模型 |\n| `include_reasoning` | bool | 是否包含推理信息 |\n| `max_triplets_per_chunk` | int | 每个块最多抽取的三元组数 |\n| `kg_extractors` | List[KGExtractor] | 知识图谱提取器列表 |\n\n#### 使用知识图谱进行检索\n\n```python\nfrom llama_index.core.indices.knowledge_graph import KnowledgeGraphIndex\n\n# 创建知识图谱索引\nindex = KnowledgeGraphIndex.from_documents(\n documents,\n max_triplets_per_chunk=10\n)\n\n# 获取检索器\nretriever = index.as_retriever(\n include_text=True,\n retriever_mode=\"keyword\"\n)\n\n# 获取查询引擎\nquery_engine = index.as_query_engine(\n include_text=True,\n response_mode=\"tree_summarize\"\n)\n\n# 执行查询\nresponse = query_engine.query(\"关于 LlamaIndex 的信息\")\n```\n\n## 检索器系统\n\n### Retriever 检索器架构\n\nRetriever 是 LlamaIndex 中负责从索引中获取相关上下文的组件。检索器采用统一的接口设计，使得不同检索策略可以透明地互换使用。\n\n```mermaid\nclassDiagram\n class BaseRetriever {\n <>\n +retrieve(str_or_query_bundle): List[NodeWithScore]\n }\n \n class VectorRetriever {\n +filters: Optional[MetadataFilters]\n +similarity_top_k: int\n +retrieve(): List[NodeWithScore]\n }\n \n class KnowledgeGraphRetriever {\n +retriever_mode: str\n +top_k: int\n +retrieve(): List[NodeWithScore]\n }\n \n class PropertyGraphRetriever {\n +include_text: bool\n +embed_relations: bool\n +retrieve(): List[NodeWithScore]\n }\n \n BaseRetriever <|-- VectorRetriever\n BaseRetriever <|-- KnowledgeGraphRetriever\n BaseRetriever <|-- PropertyGraphRetriever\n```\n\n### 检索器类型\n\n| 检索器类型 | 说明 | 适用场景 |\n|-----------|------|----------|\n| `VectorRetriever` | 基于向量相似度的检索 | 语义搜索、向量化索引 |\n| `KnowledgeGraphRetriever` | 知识图谱检索 | 关系型查询、实体链接 |\n| `PropertyGraphRetriever` | 属性图检索 | 复杂关系查询、图遍历 |\n| `KeywordTableRetriever` | 关键词表格检索 | 精确关键词匹配 |\n| `EnsembleRetriever` | 集成检索 | 组合多种检索策略 |\n\n### 自定义检索器\n\n开发者可以通过继承 BaseRetriever 类实现自定义检索逻辑：\n\n```python\nfrom llama_index.core.retrievers import BaseRetriever\nfrom llama_index.core.schema import NodeWithScore\n\nclass CustomRetriever(BaseRetriever):\n def __init__(self, index, threshold: float = 0.7):\n super().__init__()\n self._index = index\n self._threshold = threshold\n \n def _retrieve(self, query_bundle):\n # 自定义检索逻辑\n nodes = []\n # ... 实现检索逻辑\n return nodes\n```\n\n## 响应合成器\n\n### ResponseSynthesizer 响应合成器架构\n\nResponseSynthesizer 负责将检索到的上下文与用户查询结合，生成最终的自然语言响应。这是 RAG 系统中将检索结果转化为有用答案的关键环节。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Query Bundle]\n B --> C[ResponseSynthesizer]\n C --> D{合成模式}\n D -->|compact| E[Compact 压缩模式]\n D -->|refine| F[Refine 精炼模式]\n D -->|tree_summarize| G[Tree Summarize 树形摘要]\n D -->|simple| H[Simple 简单模式]\n \n E --> I[LLM 生成]\n F --> I\n G --> I\n H --> I\n I --> J[Response 响应]\n \n style C fill:#e8f5e9\n style I fill:#fff8e1\n style J fill:#c8e6c9\n```\n\n### 响应合成模式\n\nLlamaIndex 提供了多种响应合成策略，适用于不同的应用场景：\n\n| 合成模式 | 说明 | 特点 | 适用场景 |\n|---------|------|------|----------|\n| `simple` | 简单模式 | 一次性生成响应 | 简短回答、少量上下文 |\n| `compact` | 压缩模式 | 合并多个上下文块 | 大量检索结果 |\n| `refine` | 精炼模式 | 迭代优化响应 | 需要高质量长回答 |\n| `tree_summarize` | 树形摘要 | 分层聚合信息 | 复杂多主题查询 |\n| `generation` | 生成模式 | 仅使用 LLM 生成 | 无检索场景 |\n\n### 响应合成器配置\n\n```python\nfrom llama_index.core.response_synthesizers import (\n ResponseMode,\n get_response_synthesizer\n)\n\n# 创建响应合成器\nsynthesizer = get_response_synthesizer(\n response_mode=ResponseMode.COMPACT,\n llm=llm,\n text_qa_template=qa_prompt_template,\n summary_template=summary_prompt_template\n)\n\n# 通过查询引擎使用\nquery_engine = index.as_query_engine(\n response_synthesizer=synthesizer\n)\n```\n\n### 自定义响应合成器\n\n开发者可以通过继承 BaseSynthesizer 实现自定义合成逻辑：\n\n```python\nfrom llama_index.core.response_synthesizers import BaseSynthesizer\n\nclass CustomSynthesizer(BaseSynthesizer):\n def synthesize(\n self,\n query_bundle: QueryBundle,\n nodes: List[NodeWithScore]\n ) -> Response:\n # 自定义合成逻辑\n context_str = \"\\n\\n\".join([n.get_content() for n in nodes])\n # ... 生成响应\n return response\n```\n\n## 查询引擎\n\n### QueryEngine 查询引擎\n\nQueryEngine 是 LlamaIndex 提供的端到端查询接口，整合了检索和响应合成两个环节。查询引擎接收用户查询，自动执行检索流程，并生成最终响应。\n\n```mermaid\ngraph LR\n A[Query 输入] --> B[Retriever 检索]\n B --> C[NodeWithScore 节点列表]\n C --> D[Postprocessor 后处理器]\n D --> E[ResponseSynthesizer 合成器]\n E --> F[Response 输出]\n```\n\n### 查询引擎配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `retriever` | BaseRetriever | 检索器实例 |\n| `response_synthesizer` | Optional[BaseSynthesizer] | 响应合成器 |\n| `node_postprocessors` | List[BaseNodePostprocessor] | 节点后处理器 |\n| `verbose` | bool | 是否输出详细日志 |\n\n### 组合式查询引擎\n\n```python\nfrom llama_index.core import QueryEngine, get_response_synthesizer\n\n# 创建组合式查询引擎\nquery_engine = index.as_query_engine(\n retriever=retriever,\n response_synthesizer=synthesizer,\n node_postprocessors=[\n KeywordNodePostprocessor(similarity_cutoff=0.7),\n SimilarityPostprocessor(threshold=0.8)\n ]\n)\n\n# 执行查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n## 存储与持久化\n\n### StorageContext 存储上下文\n\nStorageContext 管理 LlamaIndex 的数据持久化，提供了统一的存储接口。StorageContext 封装了文档存储、向量存储、图存储等组件。\n\n```mermaid\nclassDiagram\n class StorageContext {\n +docstore: BaseDocumentStore\n +vector_store: BaseVectorStore\n +graph_store: BaseGraphStore\n +index_store: BaseIndexStore\n +from_defaults(): StorageContext\n +persist(): None\n +load(): StorageContext\n }\n \n class BaseDocumentStore {\n <>\n +add_documents(): None\n +get_document(): Document\n +delete_document(): None\n }\n \n class BaseVectorStore {\n <>\n +add(): List[str]\n +delete(): None\n +query(): VectorStoreQueryResult\n }\n \n StorageContext *-- BaseDocumentStore\n StorageContext *-- BaseVectorStore\n StorageContext *-- BaseGraphStore\n```\n\n### 持久化操作\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# 从存储加载索引\nstorage_context = StorageContext.from_defaults(\n persist_dir=\"./storage\"\n)\nindex = load_index_from_storage(storage_context)\n\n# 保存索引\nindex.storage_context.persist(persist_dir=\"./storage\")\n```\n\n## 组件交互流程\n\n### 完整 RAG 流程\n\n以下是 LlamaIndex 核心组件的完整交互流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant QE as QueryEngine\n participant Ret as Retriever\n participant VS as VectorStore\n participant Syn as ResponseSynthesizer\n participant LLM as LLM\n \n User->>QE: query(\"问题\")\n QE->>Ret: retrieve(query_bundle)\n Ret->>VS: similarity_search(embedding)\n VS-->>Ret: List[NodeWithScore]\n Ret-->>QE: List[NodeWithScore]\n QE->>Syn: synthesize(query, nodes)\n Syn->>LLM: generate(prompt)\n LLM-->>Syn: response_text\n Syn-->>QE: Response\n QE-->>User: Response\n```\n\n### 数据流向总结\n\n| 阶段 | 组件 | 数据格式 | 说明 |\n|------|------|---------|------|\n| 文档加载 | DocumentLoader | Document | 从各种来源加载原始文档 |\n| 分块处理 | NodeParser | List[Node] | 将文档分割为语义块 |\n| 向量化 | EmbedModel | List[float] | 计算文本向量表示 |\n| 索引存储 | VectorStore | VectorStoreRecord | 存储向量和元数据 |\n| 检索查询 | Retriever | List[NodeWithScore] | 根据相似度检索 |\n| 响应生成 | ResponseSynthesizer | Response | 生成自然语言回答 |\n\n## 最佳实践\n\n### 组件选择指南\n\n| 需求场景 | 推荐索引类型 | 检索器类型 |\n|---------|-------------|-----------|\n| 语义搜索 | VectorStoreIndex | VectorRetriever |\n| 关系查询 | KnowledgeGraphIndex | KnowledgeGraphRetriever |\n| 复杂关系网络 | PropertyGraphIndex | PropertyGraphRetriever |\n| 高精度问答 | VectorStoreIndex + KnowledgeGraphIndex | EnsembleRetriever |\n\n### 性能优化建议\n\n1. **批量处理**：使用批量 API 进行文档索引和检索\n2. **缓存策略**：启用向量和结果的缓存\n3. **异步操作**：使用 async API 提高并发性能\n4. **索引优化**：合理设置块大小和重叠参数\n\n### 错误处理\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\ntry:\n index = VectorStoreIndex.from_documents(documents)\n query_engine = index.as_query_engine()\n response = query_engine.query(\"问题\")\nexcept Exception as e:\n # 错误处理逻辑\n print(f\"发生错误: {e}\")\n```\n\n## 总结\n\nLlamaIndex 的核心组件体系提供了从文档处理到智能问答的完整技术栈。Document 和 Node 构成了数据模型的基础；VectorStoreIndex、PropertyGraphIndex 和 KnowledgeGraphIndex 提供了多样化的索引能力；Retriever 和 ResponseSynthesizer 则负责检索和响应生成的关键环节。这些组件通过统一的接口设计实现了高度的可组合性和可扩展性，使开发者能够灵活构建满足各种需求的 RAG 应用。\n\n---\n\n\n\n## 数据摄取流程\n\n### 相关页面\n\n相关主题：[节点解析器](#node_parsing), [存储层架构](#storage_layer), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/ingestion/pipeline.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/pipeline.py)\n- [llama-index-core/llama_index/core/readers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/base.py)\n- [llama-index-core/llama_index/core/readers/file/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/file/base.py)\n- [llama-index-core/llama_index/core/ingestion/transformations.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/transformations.py)\n \n\n# 数据摄取流程\n\n## 概述\n\n数据摄取流程（Data Ingestion Pipeline）是LlamaIndex框架中负责从各种数据源加载、转换和处理原始数据的核心模块。该流程将非结构化或半结构化的原始数据转换为标准化的Document对象，供后续的索引构建和检索使用。\n\n数据摄取流程的主要职责包括：\n\n- **数据加载**：从文件、网页、数据库、API等多种来源读取数据\n- **数据解析**：将不同格式的数据（PDF、Word、HTML、Markdown等）解析为文本内容\n- **数据转换**：对文本进行分块、清洗、向量化等预处理操作\n- **流程编排**：通过Pipeline机制协调各个处理环节\n\n```mermaid\ngraph TD\n A[数据源] --> B[Reader读取器]\n B --> C[Document对象]\n C --> D[Transformations转换器]\n D --> E[处理后的Document]\n E --> F[索引构建/存储]\n```\n\n## 核心架构\n\n数据摄取流程由三个主要组件构成：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **Reader** | 从各种来源加载原始数据 | `llama_index/core/readers/` |\n| **Transformation** | 对Document进行转换处理 | `llama_index/core/ingestion/transformations.py` |\n| **IngestionPipeline** | 编排整个摄取流程 | `llama_index/core/ingestion/pipeline.py` |\n\n## 读取器（Readers）\n\n### 读取器基类\n\n所有读取器继承自`BaseReader`基类，定义了统一的数据加载接口：\n\n```python\nfrom llama_index.core.readers.base import BaseReader\n\nclass BaseReader:\n \"\"\"数据读取器基类\"\"\"\n \n def load_data(self, *args, **kwargs) -> List[Document]:\n \"\"\"加载数据并返回Document列表\"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/readers/base.py]()\n\n### 文件读取器\n\n`SimpleDirectoryReader`是文件读取的核心实现，支持从本地目录批量加载文件：\n\n```python\nfrom llama_index.core import SimpleDirectoryReader\n\n# 从目录加载所有支持的文件\nreader = SimpleDirectoryReader(\"./data\")\ndocuments = reader.load_data()\n\n# 指定文件扩展名过滤\nreader = SimpleDirectoryReader(\n \"./data\",\n required_exts=[\".pdf\", \".docx\"]\n)\ndocuments = reader.load_data()\n\n# 递归加载子目录\nreader = SimpleDirectoryReader(\n \"./data\",\n recursive=True\n)\ndocuments = reader.load_data()\n```\n\n资料来源：[llama-index-core/llama_index/core/readers/file/base.py]()\n\n#### SimpleDirectoryReader 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `input_dir` | str | 输入目录路径 |\n| `input_files` | List[Path] | 指定要加载的文件列表 |\n| `recursive` | bool | 是否递归扫描子目录，默认False |\n| `required_exts` | List[str] | 只加载指定扩展名的文件 |\n| `exclude` | List[str] | 排除的文件名模式 |\n| `filename_as_id` | bool | 使用文件名作为Document ID |\n\n### Web读取器\n\nLlamaIndex提供多种网页内容提取器：\n\n| 读取器 | 说明 | 安装包 |\n|--------|------|--------|\n| `TrafilaturaWebReader` | 使用trafilatura提取静态网页文本 | llama-index-readers-web |\n| `UnstructuredURLLoader` | 使用Unstructured.io解析HTML | llama-index-readers-web |\n| `NewsArticleReader` | 解析新闻文章（基于newspaper3k） | llama-index-readers-web |\n| `MainContentExtractorReader` | 提取网页主体内容 | llama-index-readers-web |\n| `ReadabilityWebPageReader` | 使用Readability算法提取正文 | llama-index-readers-web |\n\n```python\nfrom llama_index.readers.web import TrafilaturaWebReader\n\nloader = TrafilaturaWebReader()\ndocuments = loader.load_data(urls=[\"https://example.com/article\"])\n```\n\n### 远程深度读取器\n\n`RemoteDepthReader`支持递归抓取指定深度的链接：\n\n```python\nfrom llama_index.readers.remote_depth import RemoteDepthReader\n\nloader = RemoteDepthReader()\n# depth=2表示提取页面链接 + 链接指向页面的链接\ndocuments = loader.load_data(\n url=\"https://example.com/\",\n depth=2\n)\n```\n\n### 文档解析读取器\n\n| 读取器 | 支持格式 | 安装包 |\n|--------|----------|--------|\n| `DoclingReader` | PDF, DOCX, HTML, JSON | llama-index-readers-docling |\n| `WikipediaReader` | Wikipedia页面 | llama-index-readers-wikipedia |\n| `WordpressReader` | WordPress博客 | llama-index-readers-wordpress |\n| `BagelReader` | Bagel向量数据库 | llama-index-readers-bagel |\n\n## 数据转换（Transformations）\n\n转换器是数据摄取流程中的关键环节，用于对Document进行分块、向量化等处理。\n\n### 转换器类型\n\n| 转换器 | 功能 | 源码位置 |\n|--------|------|----------|\n| `SentenceSplitter` | 按句子/字符数分块 | transformations.py |\n| `TokenTextSplitter` | 按Token数分块 | transformations.py |\n| `RecursiveCharacterTextSplitter` | 递归字符分块 | transformations.py |\n\n### 核心转换器详解\n\n#### SentenceSplitter\n\n按句子边界进行文本分块：\n\n```python\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\n\nsplitter = SentenceSplitter(\n chunk_size=1024, # 块大小（字符数）\n chunk_overlap=20, # 块间重叠字符数\n separator=\" \" # 分隔符\n)\n\nchunked_docs = splitter(documents)\n```\n\n#### TokenTextSplitter\n\n基于Token数量进行智能分块：\n\n```python\nfrom llama_index.core.ingestion.transformations import TokenTextSplitter\n\nsplitter = TokenTextSplitter(\n chunk_size=512, # 块大小（Token数）\n chunk_overlap=50, # 块间重叠Token数\n separator=[\"\\n\\n\", \"\\n\", \" \"] # 分隔优先级\n)\n\nchunked_docs = splitter(documents)\n```\n\n### 转换器参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | int | 1024 | 单个块的目标大小 |\n| `chunk_overlap` | int | 200 | 块间重叠大小 |\n| `separator` | str/List[str] | \"\\n\\n\" | 分隔符 |\n| `backup_separators` | List[str] | None | 备用分隔符列表 |\n\n## 摄取管道（IngestionPipeline）\n\n`IngestionPipeline`是数据摄取流程的核心编排器，协调读取器、转换器和存储后端的工作。\n\n### 基本用法\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\nfrom llama_index.core import VectorStoreIndex\n\n# 创建管道，指定转换器\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=1024, chunk_overlap=20)\n ]\n)\n\n# 对文档执行管道\nprocessed_docs = pipeline.run(documents=raw_documents)\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(processed_docs)\n```\n\n### 完整摄取流程图\n\n```mermaid\ngraph LR\n A[原始文档] --> B[管道处理]\n B --> C{是否配置存储?}\n C -->|是| D[存储到向量数据库]\n C -->|否| E[返回Document列表]\n D --> F[构建索引]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### 管道缓存\n\nIngestionPipeline支持缓存机制以提升重复执行效率：\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\n\npipeline = IngestionPipeline(\n transformations=[...],\n docstore=SimpleDocumentStore() # 启用文档缓存\n)\n\n# 首次运行会处理所有文档\ndocs1 = pipeline.run(documents=documents)\n\n# 再次运行时，已缓存的文档会被跳过\ndocs2 = pipeline.run(documents=documents)\n```\n\n## 数据摄取完整流程\n\n```mermaid\nflowchart TD\n subgraph 数据源\n A1[本地文件]\n A2[网页内容]\n A3[数据库]\n A4[API接口]\n end\n \n subgraph 读取层\n B1[FileReader]\n B2[WebReader]\n B3[APILoader]\n end\n \n subgraph 转换层\n C1[文本分块]\n C2[元数据提取]\n C3[向量化]\n end\n \n subgraph 输出层\n D1[Document对象]\n D2[向量索引]\n D3[知识图谱]\n end\n \n A1 --> B1\n A2 --> B2\n A3 --> B3\n A4 --> B3\n \n B1 --> C1\n B2 --> C1\n B3 --> C1\n \n C1 --> C2\n C2 --> C3\n \n C3 --> D1\n C3 --> D2\n C3 --> D3\n```\n\n## 使用示例\n\n### 完整文件摄取示例\n\n```python\nfrom llama_index.core import SimpleDirectoryReader, VectorStoreIndex\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\n\n# 1. 加载文档\nreader = SimpleDirectoryReader(\"./data\", recursive=True)\ndocuments = reader.load_data()\n\n# 2. 创建摄取管道\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=1024, chunk_overlap=128)\n ]\n)\n\n# 3. 处理文档\nprocessed_docs = pipeline.run(documents=documents)\n\n# 4. 构建索引\nindex = VectorStoreIndex.from_documents(processed_docs)\n\n# 5. 查询\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"相关问题\")\n```\n\n### 带向量化嵌入的摄取\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\n# 配置嵌入模型\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://localhost:11434\"\n)\n\n# 创建包含嵌入的管道\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=512),\n embed_model # 添加嵌入转换\n ]\n)\n\ndocs = pipeline.run(documents=raw_docs)\n```\n\n## 最佳实践\n\n### 1. 合理设置分块大小\n\n| 使用场景 | 推荐chunk_size | 说明 |\n|----------|----------------|------|\n| 问答系统 | 512-1024 | 适合精确答案检索 |\n| 摘要生成 | 2048-4096 | 需要更多上下文 |\n| 语义搜索 | 256-512 | 更细粒度的匹配 |\n\n### 2. 块重叠设置\n\n```python\n# 较大重叠适用于：\n# - 跨块边界的问答\n# - 需要保留上下文连贯性\n# - 文档结构不规则\n\nsplitter = SentenceSplitter(\n chunk_size=1024,\n chunk_overlap=256 # 25%重叠\n)\n```\n\n### 3. 选择合适的读取器\n\n| 数据源 | 推荐读取器 | 理由 |\n|--------|-----------|------|\n| 本地文件（多格式） | SimpleDirectoryReader | 统一接口，支持多种格式 |\n| 新闻文章 | NewsArticleReader | 专门优化新闻格式 |\n| 静态网站 | TrafilaturaWebReader | 高质量文本提取 |\n| PDF文档 | DoclingReader | 保留布局和结构 |\n\n## 相关资源\n\n- [IngestionPipeline官方文档](https://docs.llamaindex.ai/en/stable/api_reference/ingestion/)\n- [Reader集成列表](https://llamahub.ai/)\n- [Ollama嵌入模型配置](./llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n\n---\n\n\n\n## 节点解析器\n\n### 相关页面\n\n相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/node_parser/text/sentence.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/sentence.py)\n- [llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py)\n- [llama-index-core/llama_index/core/node_parser/relational/markdown_element.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/relational/markdown_element.py)\n- [llama-index-core/llama_index/core/node_parser/interface.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/interface.py)\n- [llama-index-core/llama_index/core/node_parser/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/__init__.py)\n \n\n# 节点解析器\n\n## 概述\n\n节点解析器（Node Parser）是 LlamaIndex 框架中负责将文档（Document）拆分为结构化节点（Node）序列的核心组件。在检索增强生成（RAG）工作流中，节点解析器扮演着至关重要的角色，它决定了如何将原始文本分割成适合检索和上下文处理的最小单元。\n\n节点解析器的主要职责包括：\n\n- **文本分割**：将长文档按照指定规则拆分为较小的文本块\n- **结构保留**：在分割过程中维护文档的层次结构和语义完整性\n- **元数据提取**：为每个节点附加相关的上下文信息和元数据\n- **关系建立**：建立节点之间的关系，支持后续的图结构查询\n\n资料来源：[interface.py:1-50]()\n\n## 核心接口\n\n### NodeParser 基类\n\n所有节点解析器都继承自 `NodeParser` 接口，该接口定义了节点解析的核心抽象方法。\n\n```mermaid\nclassDiagram\n class NodeParser {\n <>\n +get_nodes() List[Node]\n +get_nodes_from_documents() List[Node]\n }\n \n class BaseNodeParser {\n <>\n +get_nodes() List[Node]\n +get_nodes_from_documents() List[Node]\n }\n \n class SentenceSplitter {\n +sentence_separator: str\n +chunk_size: int\n +chunk_overlap: int\n }\n \n class SemanticSplitter {\n +embed_model: BaseEmbedding\n +buffer_size: int\n +embed_batch_size: int\n }\n \n class MarkdownElementNodeParser {\n +use_json: bool\n +merge_many_element: bool\n }\n \n NodeParser <|.. BaseNodeParser\n BaseNodeParser <|-- SentenceSplitter\n BaseNodeParser <|-- SemanticSplitter\n BaseNodeParser <|-- MarkdownElementNodeParser\n```\n\n### 核心方法\n\n| 方法名 | 参数 | 返回类型 | 说明 |\n|--------|------|----------|------|\n| `get_nodes` | documents: List[Document] | List[BaseNode] | 将文档列表转换为节点列表 |\n| `get_nodes_from_documents` | documents: List[Document], show_progress: bool | List[BaseNode] | 带进度显示的文档转换方法 |\n\n资料来源：[interface.py:50-120]()\n\n## 文本节点解析器\n\n### SentenceSplitter（句子分割器）\n\n`SentenceSplitter` 是最基本的节点解析器，它按照句子边界和字符数限制对文本进行分割。\n\n#### 主要配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | int | 1024 | 每个文本块的字符数上限 |\n| `chunk_overlap` | int | 200 | 相邻文本块之间的重叠字符数 |\n| `sentence_separator` | str | \"\\n\\n\" | 句子分隔符 |\n| `paragraph_separator` | str | \"\\n\\n\\n\" | 段落分隔符 |\n| `secondary_chunking_regex` | Optional[Pattern] | None | 次级分割正则表达式 |\n| `coalesce_chunk_size` | Optional[int] | None | 合并后的目标块大小 |\n\n#### 工作原理\n\n```mermaid\nflowchart TD\n A[输入文档] --> B[按段落分割]\n B --> C[计算段落长度]\n C --> D{段落长度 > chunk_size?}\n D -->|是| E[按句子分割段落]\n D -->|否| F[直接添加到当前块]\n E --> G{句子长度 > chunk_size?}\n G -->|是| H[按次级正则表达式分割]\n G -->|否| I[添加到当前块]\n H --> J[按chunk_size限制]\n I --> K{当前块已满?}\n J --> K\n F --> K\n K -->|是| L[创建新块]\n K -->|否| M[继续添加]\n L --> N[应用chunk_overlap]\n M --> N\n N --> O[输出节点列表]\n```\n\n资料来源：[sentence.py:1-150]()\n\n### SemanticSplitter（语义分割器）\n\n`SemanticSplitter` 是一种更高级的分割策略，它利用嵌入模型（Embedding Model）来识别语义边界，从而产生更加连贯的文本块。\n\n#### 核心概念\n\n**缓冲区机制**：SemanticSplitter 使用固定大小的缓冲区来聚合相邻句子，然后通过计算相邻缓冲区之间的语义相似度来决定分割点。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `embed_model` | BaseEmbedding | 必需 | 用于计算语义的嵌入模型 |\n| `buffer_size` | int | 1 | 相邻句子缓冲大小 |\n| `breakpoint_percent_threshold` | float | 0.5 | 触发分割的差异百分比阈值 |\n| `embed_batch_size` | int | 100 | 嵌入计算批量大小 |\n\n#### 分割策略\n\n```mermaid\nflowchart LR\n A[句子序列] --> B[缓冲区聚合]\n B --> C[计算相邻缓冲区嵌入]\n C --> D[计算余弦相似度]\n D --> E{相似度差异 > 阈值?}\n E -->|是| F[插入分割点]\n E -->|否| G[继续聚合]\n F --> H[生成语义节点]\n G --> B\n```\n\n语义分割器特别适合处理需要保持语义完整性的场景，例如问答系统、文档摘要等应用。\n\n资料来源：[semantic_splitter.py:1-200]()\n\n## Markdown 元素解析器\n\n### MarkdownElementNodeParser\n\n`MarkdownElementNodeParser` 专门用于解析 Markdown 格式的文档，它能够识别 Markdown 中的各种元素类型并分别处理。\n\n#### 支持的元素类型\n\n| 元素类型 | 说明 | 处理方式 |\n|----------|------|----------|\n| `TitleElement` | 标题元素 | 作为独立节点或用于分组 |\n| `CodeElement` | 代码块 | 保持格式，包含语言标识 |\n| `TableElement` | 表格元素 | 解析为结构化数据 |\n| `NarrativeTextElement` | 叙述文本 | 标准文本块处理 |\n| `QuestionAnswerElement` | 问答对 | 结构化问答提取 |\n\n#### 配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `use_json` | bool | False | 是否输出 JSON 格式 |\n| `include_metadata` | bool | True | 是否包含元数据 |\n| `include_prev_next_rel` | bool | True | 是否添加前后关系 |\n| `merge_many_element` | bool | True | 是否合并连续同类型元素 |\n\n#### 输出结构\n\n```mermaid\ngraph TD\n A[Markdown文档] --> B[解析标题层级]\n A --> C[提取代码块]\n A --> D[识别表格]\n A --> E[处理段落文本]\n B --> F[创建TitleElement节点]\n C --> G[创建CodeElement节点]\n D --> H[创建TableElement节点]\n E --> I[创建NarrativeTextElement节点]\n F --> J[建立标题-内容关系]\n G --> J\n H --> J\n I --> J\n J --> K[输出节点图结构]\n```\n\n当 `use_json=True` 时，解析器会输出符合 Docling 规范的 JSON 格式，需要配合 Docling Node Parser 使用。\n\n资料来源：[markdown_element.py:1-250]()\n\n## 使用指南\n\n### 基本使用示例\n\n#### 简单句子分割\n\n```python\nfrom llama_index.core.node_parser import SentenceSplitter\n\n# 初始化分割器\nnode_parser = SentenceSplitter(\n chunk_size=512,\n chunk_overlap=50\n)\n\n# 从文档获取节点\nnodes = node_parser.get_nodes_from_documents(documents)\n```\n\n#### 语义分割\n\n```python\nfrom llama_index.core.node_parser import SemanticSplitter\nfrom llama_index.core.embeddings import OpenAIEmbedding\n\n# 初始化嵌入模型\nembed_model = OpenAIEmbedding()\n\n# 创建语义分割器\nsemantic_splitter = SemanticSplitter(\n embed_model=embed_model,\n buffer_size=1,\n breakpoint_percent_threshold=0.5\n)\n\nnodes = semantic_splitter.get_nodes_from_documents(documents)\n```\n\n#### Markdown 解析\n\n```python\nfrom llama_index.core.node_parser import MarkdownElementNodeParser\n\nparser = MarkdownElementNodeParser(\n use_json=False,\n merge_many_element=True\n)\n\nnodes = parser.get_nodes_from_documents(markdown_documents)\n```\n\n### 高级配置\n\n```python\nfrom llama_index.core.node_parser import SentenceSplitter\n\n# 精细化配置\nsplitter = SentenceSplitter(\n chunk_size=1024,\n chunk_overlap=200,\n sentence_separator=\"。\", # 中文句号\n paragraph_separator=\"\\n\\n\",\n secondary_chunking_regex=\"[^，,]+[,，]?\", # 按逗号次级分割\n coalesce_chunk_size=None # 禁用合并\n)\n```\n\n## 架构设计\n\n### 节点类型层次结构\n\n```mermaid\nclassDiagram\n class BaseNode {\n <>\n +id_: str\n +embedding: Optional[List[float]]\n +metadata: Dict\n +relationships: Dict\n }\n \n class TextNode {\n +text: str\n +start_char_idx: int\n +end_char_idx: int\n }\n \n class IndexNode {\n +index_id: str\n +node_id: str\n }\n \n class DocumentRelationship {\n +SOURCE, PREVIOUS, NEXT, PARENT, CHILD\n }\n \n BaseNode <|-- TextNode\n BaseNode <|-- IndexNode\n```\n\n### 数据流\n\n```mermaid\nflowchart TD\n subgraph 输入层\n A1[Document对象]\n A2[文本内容]\n A3[元数据字典]\n end\n \n subgraph 解析层\n B1[节点解析器选择]\n B2[文本分割逻辑]\n B3[边界检测]\n end\n \n subgraph 处理层\n C1[节点创建]\n C2[关系建立]\n C3[元数据附加]\n end\n \n subgraph 输出层\n D1[BaseNode列表]\n D2[节点关系图]\n end\n \n A1 --> B1\n A2 --> B2\n A3 --> B3\n B1 --> C1\n B2 --> C2\n B3 --> C3\n C1 --> D1\n C2 --> D2\n```\n\n## 最佳实践\n\n### 分割策略选择指南\n\n| 应用场景 | 推荐解析器 | 理由 |\n|----------|-----------|------|\n| 通用文档处理 | SentenceSplitter | 简单高效，开销小 |\n| 语义连贯性要求高 | SemanticSplitter | 保持语义完整性 |\n| Markdown 文档 | MarkdownElementNodeParser | 保留文档结构 |\n| 代码文档 | MarkdownElementNodeParser | 保护代码块 |\n| 结构化数据 | MarkdownElementNodeParser | 解析表格和列表 |\n\n### 参数调优建议\n\n**chunk_size 设置**：\n\n- 小块（256-512）：适合精确检索，高细粒度\n- 中块（512-1024）：平衡检索精度和上下文完整性\n- 大块（1024-2048）：适合需要完整语境的查询\n\n**chunk_overlap 设置**：\n\n- 通常设置为 chunk_size 的 10%-20%\n- 过高会增加冗余和处理时间\n- 适用于边界信息重要的场景\n\n## 相关模块\n\n节点解析器与其他 LlamaIndex 核心组件协同工作：\n\n- **Document**：原始文档输入\n- **VectorStoreIndex**：节点用于向量索引构建\n- **BaseEmbedding**：语义分割依赖的嵌入模型\n- **Retriever**：基于节点进行信息检索\n\n## 总结\n\n节点解析器是 LlamaIndex 数据处理管道中的关键环节，它通过多种策略将非结构化文档转换为结构化的节点序列。框架提供了从简单到复杂的多种解析器实现，开发者可以根据具体需求选择合适的工具。正确配置节点解析器对于构建高效的 RAG 系统至关重要。\n\n资料来源：[__init__.py:1-50]()\n\n---\n\n\n\n## 存储层架构\n\n### 相关页面\n\n相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)\n- [llama-index-core/llama_index/core/vector_stores/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/vector_stores/types.py)\n- [llama-index-core/llama_index/core/storage/docstore/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/types.py)\n- [llama-index-core/llama_index/core/storage/chat_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/chat_store/base.py)\n \n\n# 存储层架构\n\n## 概述\n\nLlamaIndex 的存储层架构是一套完整的数据持久化解决方案，负责管理向量数据、文档数据、聊天记录等核心数据的存储与检索。该架构采用模块化设计，通过抽象接口支持多种存储后端，使开发者能够灵活选择适合自身场景的存储方案。\n\n存储层主要由三个核心组件构成：**VectorStore**（向量存储）、**Docstore**（文档存储）和 **ChatStore**（聊天存储）。这些组件通过统一的 **StorageContext**（存储上下文）进行协调管理，实现了数据访问与存储实现的解耦。\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[StorageContext] --> B[VectorStore]\n A --> C[Docstore]\n A --> C1[IndexStore]\n A --> D[ChatStore]\n A --> E[ImageStore]\n \n B --> B1[SimpleVectorStore]\n B --> B2[FaissVectorStore]\n B --> B3[MilvusVectorStore]\n B --> B4[PineconeVectorStore]\n \n C --> C2[SimpleDocstore]\n C --> C3[MongoDocstore]\n C --> C4[DynamoDBDocstore]\n \n D --> D1[SimpleChatStore]\n D --> D2[RedisChatStore]\n```\n\n### 存储上下文（StorageContext）\n\nStorageContext 是 LlamaIndex 存储层的中央协调器，负责初始化和管理所有存储组件的实例。它提供了统一的接口来访问向量存储、文档存储、索引存储和聊天存储。\n\n**主要属性：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `vector_store` | VectorStore | 向量存储实例 |\n| `docstore` | BaseDocstore | 文档存储实例 |\n| `index_store` | IndexStore | 索引存储实例 |\n| `chat_store` | ChatStore | 聊天存储实例 |\n| `image_store` | ImageStore | 图片存储实例 |\n\n**持久化方法：**\n\n```python\n# 持久化到磁盘\nindex.storage_context.persist(persist_dir=\"./storage\")\n\n# 从磁盘加载\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\nindex = load_index_from_storage(storage_context)\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py]()\n\n## 向量存储层（VectorStore）\n\n### 向量存储类型定义\n\n向量存储层负责存储和检索高维向量嵌入，是 RAG（检索增强生成）系统的核心组件。\n\n```mermaid\nclassDiagram\n class VectorStore {\n <>\n +add() List[str]\n +delete() None\n +query() List[Node]\n +get_nodes() List[BaseNode]\n +get_metadata_dict() Dict\n +delete_ref_doc() None\n +persist() None\n }\n \n class BasePydanticVectorStore {\n <>\n +client: Any\n }\n \n class VectorStoreQuery {\n <>\n +query_embedding: Optional[List[float]]\n +similarity_top_k: int\n +mode: VectorStoreQueryMode\n +filters: Optional[MetadataFilters]\n }\n \n VectorStore <|-- BasePydanticVectorStore\n```\n\n### 查询模式\n\n| 模式 | 说明 |\n|------|------|\n| `DEFAULT` | 默认相似度搜索 |\n| `MMR` | 最大边际相关性（Maximal Marginal Relevance） |\n| `HYBRID` | 混合搜索（向量+关键词） |\n\n### 查询参数结构\n\n```python\n@dataclass\nclass VectorStoreQuery:\n query_embedding: Optional[List[float]] = None\n query_str: Optional[str] = None\n similarity_top_k: int = 4\n docs: Optional[List[Document]] = None\n alpha: float = 0.5 # 用于混合搜索的权重\n nn: Optional[NearestNeighborsAlgo] = None\n mode: VectorStoreQueryMode = VectorStoreQueryMode.DEFAULT\n filters: Optional[MetadataFilters] = None\n MMR: bool = False\n mmr_threshold: Optional[float] = None\n```\n\n资料来源：[llama-index-core/llama_index/core/vector_stores/types.py]()\n\n## 文档存储层（Docstore）\n\n### 文档存储接口\n\n文档存储层负责存储原始文档及其元数据，为索引构建和检索提供文档基础。\n\n```mermaid\ngraph LR\n A[Document] --> B[BaseDocstore]\n B --> C1[SimpleDocstore]\n B --> C2[MongoDocstore]\n B --> C3[DynamoDBDocstore]\n B --> C4[ElasticsearchDocstore]\n```\n\n### 文档存储类型\n\n| 类型 | 后端 | 适用场景 |\n|------|------|----------|\n| SimpleDocstore | 内存/本地文件 | 开发测试、小规模数据 |\n| MongoDocstore | MongoDB | 分布式部署、大规模数据 |\n| DynamoDBDocstore | AWS DynamoDB | 云原生应用、高可用需求 |\n| ElasticsearchDocstore | Elasticsearch | 全文搜索场景 |\n\n### 文档数据结构\n\n```python\n@dataclass\nclass Document:\n id_: str\n embedding: Optional[List[float]] = None\n metadata: Dict[str, Any] = field(default_factory=dict)\n excluded_embed_metadata_keys: List[str] = field(default_factory=list)\n excluded_llm_metadata_keys: List[str] = field(default_factory=list)\n relationships: Dict[DocumentRelationship, List[str]] = field(default_factory=dict)\n hash: Optional[str] = None\n text: str = \"\"\n start_char_idx: Optional[int] = None\n end_char_idx: Optional[int] = None\n text_template: str = \"{metadata_str}\\n\\n{content}\"\n metadata_template: str = \"{key}: {value}\"\n metadata_separator: str = \"\\n\"\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/docstore/types.py]()\n\n## 聊天存储层（ChatStore）\n\n### 聊天存储架构\n\n聊天存储层用于持久化管理对话历史，支持多轮对话场景和上下文管理。\n\n```mermaid\ngraph TD\n A[ChatMessage] --> B[BaseChatStore]\n B --> C1[SimpleChatStore]\n B --> C2[RedisChatStore]\n B --> C3[MongoChatStore]\n \n D[ChatStoreConfig] --> B\n E[ChatSession] --> D\n```\n\n### 聊天消息类型\n\n| 类型 | 说明 |\n|------|------|\n| `ChatMessageRole.AI` | AI 助手消息 |\n| `ChatMessageRole.USER` | 用户消息 |\n| `ChatMessageRole.SYSTEM` | 系统消息 |\n| `ChatMessageRole.TOOL` | 工具消息 |\n\n### 聊天存储接口\n\n```python\nclass BaseChatStore(ABC):\n @abstractmethod\n def add_message(self, key: str, message: ChatMessage) -> None:\n pass\n \n @abstractmethod\n def get_messages(self, key: str) -> List[ChatMessage]:\n pass\n \n @abstractmethod\n def delete_messages(self, key: str) -> None:\n pass\n \n @abstractmethod\n def delete_message(self, key: str, idx: int) -> None:\n pass\n \n @abstractmethod\n def delete_all_messages(self, key: str) -> None:\n pass\n \n @abstractmethod\n def get_latest_message(self, key: str) -> Optional[ChatMessage]:\n pass\n \n @abstractmethod\n def as_langchain_chat_history(self, **kwargs: Any) -> BaseChatMessageHistory:\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/chat_store/base.py]()\n\n## 数据流与工作流程\n\n### 索引构建流程\n\n```mermaid\ngraph TD\n A[加载文档] --> B[文本分块]\n B --> C[生成嵌入向量]\n C --> D[存储到Docstore]\n C --> E[存储到VectorStore]\n D --> F[构建索引结构]\n E --> F\n F --> G[持久化存储]\n```\n\n### 检索查询流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询向量化]\n B --> C[向量相似度搜索]\n C --> D{混合搜索?}\n D -->|是| E[关键词搜索]\n D -->|否| F[获取Top-K结果]\n E --> F\n F --> G[结果重排序]\n G --> H[返回上下文]\n```\n\n## 存储配置选项\n\n### StorageContext 构造参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vector_store` | VectorStore | SimpleVectorStore | 向量存储实例 |\n| `docstore` | BaseDocstore | SimpleDocumentStore | 文档存储实例 |\n| `index_store` | IndexStore | SimpleIndexStore | 索引存储实例 |\n| `chat_store` | ChatStore | None | 聊天存储实例 |\n| `persist_dir` | str | None | 持久化目录路径 |\n| `graph_store` | GraphStore | None | 知识图谱存储 |\n\n### 持久化配置\n\n```python\n# 完整配置示例\nstorage_context = StorageContext.from_defaults(\n vector_store=vector_store,\n docstore=docstore,\n index_store=index_store,\n persist_dir=\"./storage\"\n)\n\n# 手动持久化\nstorage_context.persist(persist_dir=\"./storage\")\n\n# 从持久化目录加载\nstorage_context = StorageContext.from_defaults(\n persist_dir=\"./storage\"\n)\n```\n\n## 存储后端兼容性\n\n### 向量存储后端矩阵\n\n| 后端 | 支持元数据过滤 | 支持混合搜索 | 支持删除 | 支持更新 |\n|------|---------------|-------------|---------|---------|\n| SimpleVectorStore | ✅ | ❌ | ✅ | ❌ |\n| Faiss | ✅ | ❌ | ❌ | ❌ |\n| Pinecone | ✅ | ✅ | ✅ | ✅ |\n| Weaviate | ✅ | ✅ | ✅ | ✅ |\n| Milvus | ✅ | ✅ | ✅ | ✅ |\n| Chroma | ✅ | ❌ | ✅ | ❌ |\n\n## 最佳实践\n\n### 生产环境存储配置\n\n1. **向量存储选择**：对于大规模向量检索场景，推荐使用专门的向量数据库如 Milvus、Pinecone 或 Weaviate\n2. **文档存储选择**：需要支持事务和分布式部署时，选择 MongoDB 或 DynamoDB\n3. **数据持久化**：生产环境务必配置持久化，定期备份存储目录\n\n### 性能优化建议\n\n| 场景 | 优化策略 |\n|------|----------|\n| 大规模向量检索 | 使用支持索引的向量数据库，调整 `similarity_top_k` 参数 |\n| 高频写入 | 批量写入，使用异步持久化 |\n| 内存限制 | 使用磁盘持久化的存储后端，及时释放缓存 |\n| 多模态数据 | 分离图片存储和文本存储，独立管理 |\n\n## 总结\n\nLlamaIndex 的存储层架构通过抽象化的接口设计，实现了存储逻辑与业务逻辑的解耦。开发者可以根据实际需求选择合适的存储后端，无需修改上层代码即可切换存储方案。StorageContext 作为统一的入口，提供了简洁的配置接口和持久化机制，确保了数据的安全性和可移植性。\n\n---\n\n\n\n## 智能体系统\n\n### 相关页面\n\n相关主题：[工作流引擎](#workflow_engine), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/agent/react/formatter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/react/formatter.py)\n- [llama-index-core/llama_index/core/agent/workflow/base_agent.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/base_agent.py)\n- [llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py)\n- [llama-index-core/llama_index/core/tools/function_tool.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/tools/function_tool.py)\n \n\n# 智能体系统\n\n## 概述\n\nLlamaIndex 的智能体系统（Agent System）是一个用于构建、编排和管理基于大型语言模型（LLM）的智能体的核心框架。该系统提供了灵活的架构，支持单智能体和多智能体工作流，使开发者能够创建能够执行复杂任务、调用外部工具、处理多轮对话的 AI 应用。\n\n智能体系统的核心设计理念是将 LLM 与外部工具、数据源和执行环境解耦，通过标准化的接口实现智能体的感知、推理和行动能力。\n\n## 核心架构\n\n### 系统组件关系图\n\n```mermaid\ngraph TD\n User[用户] --> Agent[智能体]\n Agent --> Tool[工具集]\n Agent --> LLM[大语言模型]\n Agent --> Memory[记忆模块]\n Tool --> ExternalAPI[外部 API]\n Tool --> Function[函数调用]\n Tool --> DataSource[数据源]\n Memory --> Context[上下文存储]\n```\n\n### 核心模块\n\n| 模块名称 | 功能描述 | 主要类 |\n|---------|---------|--------|\n| Agent Core | 智能体核心引擎 | `BaseAgent`, `ReActAgent` |\n| Workflow | 工作流编排 | `MultiAgentWorkflow` |\n| Tools | 工具管理 | `FunctionTool`, `QueryTool` |\n| Memory | 记忆管理 | `ChatMemory`, `ContextMemory` |\n| Formatter | 输出格式化 | `ReActFormatter` |\n\n## ReAct 智能体\n\n### 工作原理\n\nReAct（Reasoning + Acting）智能体是 LlamaIndex 实现的核心智能体类型之一，它通过交替执行推理（Reasoning）和行动（Acting）步骤来解决问题。\n\n```mermaid\ngraph LR\n A[用户输入] --> B[LLM 推理]\n B --> C[生成行动]\n C --> D[执行工具]\n D --> E[观察结果]\n E --> B\n B --> F{是否完成}\n F -->|是| G[返回结果]\n F -->|否| B\n```\n\n### ReActFormatter\n\n`ReActFormatter` 负责为 ReAct 智能体生成格式化的提示词模板，它定义了智能体在推理过程中的思考框架和行动规范。\n\n主要功能包括：\n\n- 生成系统提示词模板\n- 定义思考（Thought）、行动（Action）、观察（Observation）的格式规范\n- 管理工具调用的上下文信息\n\n**文件位置：** `llama-index-core/llama_index/core/agent/react/formatter.py`\n\n## 工作流系统\n\n### BaseAgent 基础类\n\n`BaseAgent` 是所有智能体的基类，定义了智能体的核心接口和行为规范。\n\n| 方法 | 功能描述 |\n|-----|---------|\n| `chat()` | 处理单轮对话 |\n| `chat_with_sources()` | 返回带来源的对话结果 |\n| `reset()` | 重置智能体状态 |\n| `stream_chat()` | 流式对话处理 |\n\n### 多智能体工作流\n\n`MultiAgentWorkflow` 实现了多智能体协作框架，允许定义多个专业化的智能体并协调它们之间的交互。\n\n```mermaid\ngraph TD\n A[用户请求] --> B[调度器]\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```\n\n**文件位置：** `llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py`\n\n## 工具系统\n\n### FunctionTool\n\n`FunctionTool` 是 LlamaIndex 中用于封装可调用函数的工具类，它将 Python 函数转换为智能体可以调用的工具。\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\n# 定义一个函数\ndef search_database(query: str) -> str:\n \"\"\"在数据库中搜索相关信息\"\"\"\n # 实现搜索逻辑\n return f\"找到关于 {query} 的结果\"\n\n# 转换为工具\nsearch_tool = FunctionTool.from_defaults(\n fn=search_database,\n name=\"database_search\",\n description=\"用于搜索数据库中的信息\"\n)\n```\n\n### 工具特性\n\n| 特性 | 说明 |\n|-----|-----|\n| 函数包装 | 将 Python 函数转换为可被智能体调用的工具 |\n| 元数据管理 | 支持 name、description 等元数据定义 |\n| 参数验证 | 自动验证输入参数类型和格式 |\n| 结果序列化 | 处理函数返回值以供 LLM 理解 |\n\n**文件位置：** `llama-index-core/llama_index/core/tools/function_tool.py`\n\n## 智能体执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 智能体\n participant L as LLM\n participant T as 工具\n participant M as 记忆\n\n U->>A: 发送请求\n A->>M: 获取上下文\n A->>L: 生成推理\n L-->>A: 返回思考结果\n A->>T: 调用工具\n T-->>A: 返回观察结果\n A->>L: 基于观察继续推理\n L-->>A: 返回最终决策\n A->>M: 更新记忆\n A-->>U: 返回响应\n```\n\n## 使用示例\n\n### 创建基础智能体\n\n```python\nfrom llama_index.core.agent import ReActAgent\nfrom llama_index.core.tools import FunctionTool\nfrom llama_index.llms.openai import OpenAI\n\n# 初始化 LLM\nllm = OpenAI(model=\"gpt-4\")\n\n# 创建工具\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 今天是晴天，25°C\"\n\nweather_tool = FunctionTool.from_defaults(\n fn=get_weather,\n name=\"get_weather\",\n description=\"获取特定位置的天气信息\"\n)\n\n# 创建智能体\nagent = ReActAgent.from_tools(\n tools=[weather_tool],\n llm=llm,\n verbose=True\n)\n\n# 对话\nresponse = agent.chat(\"北京的天气怎么样？\")\nprint(response)\n```\n\n### 多智能体协作\n\n```python\nfrom llama_index.core.agent.workflow import MultiAgentWorkflow\n\n# 创建多个专业智能体\nresearch_agent = ReActAgent.from_tools(...)\nanalysis_agent = ReActAgent.from_tools(...)\n\n# 创建工作流\nworkflow = MultiAgentWorkflow(agents=[\n research_agent,\n analysis_agent\n])\n\n# 执行工作流\nresult = workflow.run(task=\"分析市场趋势\")\n```\n\n## 配置选项\n\n### 智能体配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `max_iterations` | int | 10 | 最大迭代次数 |\n| `timeout` | float | 60.0 | 单次工具调用超时时间（秒） |\n| `verbose` | bool | False | 是否输出详细日志 |\n| `tool_choice` | str | \"auto\" | 工具选择策略 |\n\n### 工具配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `name` | str | 必填 | 工具名称 |\n| `description` | str | 必填 | 工具描述（LLM 使用） |\n| `fn_schema` | BaseModel | None | 函数参数模式 |\n| `return_direct` | bool | False | 是否直接返回结果 |\n\n## 最佳实践\n\n### 1. 工具设计原则\n\n- 为每个工具提供清晰、具体的描述\n- 使用类型提示定义参数模式\n- 保持工具职责单一性\n- 处理异常情况并返回有意义的错误信息\n\n### 2. 智能体配置建议\n\n- 根据任务复杂度调整 `max_iterations`\n- 设置合理的超时时间\n- 使用 `verbose=True` 进行调试\n- 合理管理智能体的记忆和上下文\n\n### 3. 性能优化\n\n- 批量处理独立的工具调用\n- 使用缓存减少重复计算\n- 限制上下文长度以控制成本\n- 选择合适的 LLM 模型\n\n## 扩展开发\n\n### 自定义智能体类型\n\n```python\nfrom llama_index.core.agent import BaseAgent\n\nclass CustomAgent(BaseAgent):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n \n def chat(self, message: str) -> Response:\n # 实现自定义对话逻辑\n pass\n \n def reset(self) -> None:\n # 实现重置逻辑\n pass\n```\n\n### 自定义工具类型\n\n```python\nfrom llama_index.core.tools import BaseTool\n\nclass CustomTool(BaseTool):\n @property\n def name(self) -> str:\n return \"custom_tool\"\n \n @property\n def description(self) -> str:\n return \"自定义工具描述\"\n \n def _call(self, *args, **kwargs) -> str:\n # 实现工具逻辑\n pass\n```\n\n## 相关资源\n\n- 官方文档：[LlamaIndex Agent Documentation](https://docs.llamaindex.ai/en/stable/module_guides/agents/)\n- 示例代码：[Agent Examples](https://github.com/run-llama/llama_index/tree/main/docs/examples/agent)\n- 源码仓库：[llama-index-core/agent](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/agent)\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[智能体系统](#agent_system), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/workflow/workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/workflow.py)\n- [llama-index-core/llama_index/core/workflow/context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/context.py)\n- [llama-index-core/llama_index/core/workflow/events.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/events.py)\n- [llama-index-core/llama_index/core/workflow/handler.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/handler.py)\n\n \n\n# 工作流引擎\n\n## 概述\n\nLlamaIndex 工作流引擎（Workflow Engine）是一个基于事件驱动架构的异步任务编排框架，专为构建复杂的大型语言模型（LLM）应用而设计。该引擎允许开发者通过声明式的方式定义工作流步骤（Step），并通过事件的发布与订阅机制来实现步骤之间的通信与协作。\n\n工作流引擎的核心价值在于解耦应用逻辑，使开发者能够将复杂的 LLM 任务分解为独立的、可复用的步骤，同时保持对这些步骤执行顺序和依赖关系的精确控制。\n\n## 核心架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[Workflow 工作流] --> B[Context 上下文]\n A --> C[Event 事件]\n A --> D[Step 步骤]\n C --> E[StartEvent 启动事件]\n C --> F[StopEvent 停止事件]\n C --> G[CustomEvent 自定义事件]\n D --> H[StartDecorator 启动装饰器]\n D --> I[StepDecorator 步骤装饰器]\n B --> J[State 状态管理]\n J --> K[变量存取]\n B --> L[流式数据处理]\n L --> M[迭代器支持]\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 职责说明 |\n|---------|---------|---------|\n| Workflow | workflow.py | 工作流容器，管理所有步骤和事件路由 |\n| Context | context.py | 提供步骤间的状态共享和数据传递能力 |\n| Event | events.py | 定义事件基类及内置事件类型 |\n| WorkflowHandler | handler.py |管理工作流执行，处理异步任务调度 |\n\n## 事件系统\n\n事件系统是工作流引擎的通信基础，采用发布-订阅模式实现步骤间的松耦合交互。\n\n### 内置事件类型\n\n事件系统定义在 `events.py` 文件中，提供了基础的事件抽象类和预定义事件类型。\n\n```mermaid\ngraph LR\n A[事件发布] --> B[EventBus 事件总线]\n B --> C[Step 步骤处理]\n C --> D[新事件发布]\n D --> B\n```\n\n### 事件类型表\n\n| 事件类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| StartEvent | 工作流启动时触发的事件 | 初始化工作流、传递启动参数 |\n| StopEvent | 工作流停止时触发的事件 | 清理资源、返回最终结果 |\n| CustomEvent | 自定义事件类型 | 步骤间自定义通信 |\n\n事件类采用 Pydantic 模型定义，确保类型安全和序列化能力：\n\n```python\nclass Event(BaseModel):\n \"\"\"基础事件类\"\"\"\n pass\n\nclass StartEvent(Event):\n \"\"\"工作流启动事件\"\"\"\n pass\n\nclass StopEvent(Event):\n \"\"\"工作流停止事件\"\"\"\n pass\n\nclass CustomEvent(Event):\n \"\"\"自定义事件\"\"\"\n name: str\n msg: str = \"\"\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/events.py:1-50]()\n\n## 工作流上下文\n\n上下文（Context）对象在整个工作流执行期间维护状态信息，并提供步骤间数据共享的机制。\n\n### 上下文核心功能\n\n上下文对象提供以下核心能力：\n\n| 功能 | 说明 |\n|-----|------|\n| 状态存储 | 存储和检索工作流执行过程中的数据 |\n| 事件发布 | 允许步骤发布新事件触发后续处理 |\n| 流式处理 | 支持异步迭代器处理流式数据 |\n\n### 上下文 API\n\n```python\nclass Context:\n \"\"\"工作流上下文基类\"\"\"\n \n async def get(self, key: str, default: Any = None) -> Any:\n \"\"\"获取上下文变量\"\"\"\n pass\n \n async def set(self, key: str, value: Any) -> None:\n \"\"\"设置上下文变量\"\"\"\n pass\n \n async def publish_event(self, event: Event) -> None:\n \"\"\"发布事件\"\"\"\n pass\n \n async def stream_output(\n self, \n stream_type: str, \n _id: str, \n iterator: AsyncIterator\n ) -> None:\n \"\"\"流式输出处理\"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/context.py:1-100]()\n\n### 状态管理流程\n\n```mermaid\nsequenceDiagram\n participant Step1 as 步骤1\n participant Context as 上下文\n participant Step2 as 步骤2\n \n Step1->>Context: set(\"result\", data)\n Note over Step1,Context: 存储中间结果\n Step1->>Context: publish_event(CustomEvent)\n Note over Context: 触发后续处理\n Step2->>Context: get(\"result\")\n Note over Step2: 获取前置步骤结果\n```\n\n## 工作流定义\n\n### 步骤装饰器\n\n工作流通过装饰器模式定义步骤，支持灵活的声明式语法。\n\n#### 装饰器类型\n\n| 装饰器 | 说明 | 适用场景 |\n|-------|------|---------|\n| @start | 标记工作流入口点 | 定义初始步骤 |\n| @step | 标记常规处理步骤 | 业务逻辑处理 |\n\n### 工作流类定义\n\n```python\nclass Workflow(BaseModel, ABC):\n \"\"\"工作流基类\"\"\"\n \n def __init__(\n self,\n timeout: Optional[float] = None,\n disable_validation: bool = False,\n **kwargs: Any\n ):\n \"\"\"初始化工作流\n \n Args:\n timeout: 工作流超时时间（秒）\n disable_validation: 是否禁用步骤验证\n \"\"\"\n self.timeout = timeout\n self._steps: List[Any] = []\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/workflow.py:1-100]()\n\n### 工作流示例结构\n\n```mermaid\ngraph TD\n A[@start] --> B[初始化步骤]\n B --> C[处理步骤1]\n C --> D{条件判断}\n D -->|条件A| E[处理步骤2A]\n D -->|条件B| F[处理步骤2B]\n E --> G[聚合步骤]\n F --> G\n G --> H[@stop]\n```\n\n## 工作流处理器\n\nWorkflowHandler 负责管理工作流的实际执行，包括异步调度、错误处理和结果收集。\n\n### 处理器核心职责\n\n| 职责 | 说明 |\n|-----|------|\n| 任务调度 | 管理步骤的执行顺序和并发 |\n| 事件路由 | 将事件分发给对应的步骤处理 |\n| 结果收集 | 收集并汇总工作流执行结果 |\n| 错误传播 | 处理执行过程中的异常 |\n\n### 处理器执行流程\n\n```mermaid\nflowchart TD\n A[创建处理器] --> B{超时检查}\n B -->|未超时| C[获取待处理事件]\n B -->|超时| Z[抛出TimeoutError]\n C --> D{存在待处理事件?}\n D -->|是| E[执行对应步骤]\n D -->|否| F{所有步骤完成?}\n E --> G[产生新事件]\n G --> C\n F -->|是| H[返回结果]\n F -->|否| C\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/handler.py:1-100]()\n\n## 异步执行模型\n\n### 异步迭代器支持\n\n工作流引擎原生支持流式数据处理，允许步骤返回异步迭代器：\n\n```python\nasync def process_stream(self, ctx: Context) -> AsyncIterator[str]:\n \"\"\"处理流式数据\"\"\"\n for chunk in data_source:\n yield chunk\n await ctx.publish_event(StreamChunkEvent(data=chunk))\n```\n\n### 流式输出处理\n\n上下文提供专门的流式输出管理机制：\n\n```python\nasync def stream_output(\n self, \n stream_type: str, \n _id: str, \n iterator: AsyncIterator\n) -> None:\n \"\"\"处理步骤产生的流式输出\n \n Args:\n stream_type: 流类型标识\n _id: 流实例唯一标识\n iterator: 异步迭代器对象\n \"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/context.py:50-80]()\n\n## 使用模式\n\n### 基础工作流定义\n\n```python\nfrom llama_index.core.workflow import Workflow, StartEvent, StopEvent, step\n\nclass MyWorkflow(Workflow):\n @step\n async def start(self, ev: StartEvent) -> StopEvent:\n # 初始化处理\n return StopEvent(result=\"complete\")\n```\n\n### 多步骤工作流\n\n```python\nclass MultiStepWorkflow(Workflow):\n @step\n async def step_a(self, ev: StartEvent) -> StepBEvent:\n result_a = await self.process_a(ev.data)\n return StepBEvent(data=result_a)\n \n @step\n async def step_b(self, ev: StepBEvent) -> StopEvent:\n result = await self.process_b(ev.data)\n return StopEvent(result=result)\n```\n\n### 事件驱动交互\n\n```python\nfrom llama_index.core.workflow import Event\n\nclass DataEvent(Event):\n data: Any\n\nclass EventDrivenWorkflow(Workflow):\n @step\n async def producer(self, ctx: Context, ev: StartEvent):\n for item in data_items:\n await ctx.publish_event(DataEvent(data=item))\n \n @step\n async def consumer(self, ctx: Context, ev: DataEvent):\n result = await self.process(ev.data)\n await ctx.set(\"results\", ctx.get(\"results\", []) + [result])\n```\n\n## 配置选项\n\n### 工作流配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| timeout | float | None | 工作流最大执行时间（秒），None 表示无限制 |\n| disable_validation | bool | False | 是否跳过步骤注册验证 |\n| **kwargs | Any | - | 其他传递给基类的参数 |\n\n### 事件配置\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| name | str | 事件名称标识 |\n| msg | str | 事件携带的消息内容 |\n| data | Any | 事件携带的业务数据 |\n\n## 与 LlamaIndex 生态集成\n\n工作流引擎是 LlamaIndex 核心基础设施的一部分，可与其他组件无缝协作：\n\n| 集成组件 | 集成方式 |\n|---------|---------|\n| LLM 模块 | 通过 @step 装饰的步骤调用 LLM |\n| Reader 模块 | 工作流中使用 Reader 加载外部数据 |\n| Agent 模块 | 工作流可包装 Agent 能力 |\n| Query Pipeline | 与查询管道进行数据交换 |\n\n## 最佳实践\n\n### 1. 步骤粒度设计\n\n保持步骤职责单一，每个步骤应该只完成一个明确的任务。复杂的业务逻辑应该拆分为多个步骤，而不是在一个步骤中完成所有处理。\n\n### 2. 事件命名规范\n\n使用清晰的事件命名约定，例如 `StepACompleteEvent`、`DataProcessedEvent` 等，便于理解工作流的数据流向。\n\n### 3. 状态管理策略\n\n- 仅在上下文存储必要的共享状态\n- 避免在上下文中存储大型对象\n- 使用唯一标识符管理多个数据实例\n\n### 4. 错误处理\n\n```python\n@step\nasync def safe_step(self, ctx: Context, ev: InputEvent) -> OutputEvent:\n try:\n result = await self.unsafe_operation(ev.data)\n return OutputEvent(data=result)\n except Exception as e:\n await ctx.publish_event(ErrorEvent(error=str(e)))\n raise\n```\n\n### 5. 超时控制\n\n```python\nworkflow = MyWorkflow(timeout=60.0) # 60秒超时\nresult = await workflow.run()\n```\n\n## 总结\n\nLlamaIndex 工作流引擎提供了一个强大而灵活的异步任务编排框架，通过事件驱动的设计模式使开发者能够构建复杂的 LLM 应用流程。其核心优势包括：\n\n- **声明式定义**：通过装饰器轻松定义工作流步骤\n- **事件驱动通信**：松耦合的步骤间交互机制\n- **异步执行**：原生支持异步编程模式\n- **状态共享**：上下文对象提供可靠的数据传递\n- **流式处理**：内置异步迭代器支持\n\n工作流引擎的模块化设计使其能够适应各种复杂度的应用场景，从简单的线性处理到复杂的多分支并发工作流都能得到良好支持。\n\n---\n\n\n\n## 查询引擎\n\n### 相关页面\n\n相关主题：[核心组件详解](#core_components)\n\n对不起，我无法完成此请求。\n\n**问题说明：**\n\n您要求基于以下源码文件生成关于\"查询引擎\"的Wiki页面：\n\n- `llama-index-core/llama_index/core/query_engine/retriever_query_engine.py`\n- `llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py`\n- `llama-index-core/llama_index/core/query_engine/flare/base.py`\n- `llama-index-core/llama_index/core/query_engine/knowledge_graph_query_engine.py`\n\n但当前提供的上下文（START_OF_CONTEXT）中**不包含这些文件**。上下文仅包含以下类型的README文件：\n\n| 类型 | 数量 |\n|------|------|\n| Readers集成（Web、Wikipedia、Wordpress等） | 15+ |\n| Tools集成（Moss、Brightdata、Exa） | 3 |\n| 其他集成（Docling、Box、Chroma等） | 若干 |\n\n**缺失的关键内容：**\n\n- 查询引擎的Python实现源码\n- 查询引擎的类定义和方法签名\n- 查询引擎的内部逻辑和架构\n- 配置文件和参数定义\n\n**建议：**\n\n1. 请提供完整的查询引擎源码文件内容\n2. 或者调整Wiki页面主题为当前上下文中实际包含的内容（如\"数据读取器\"或\"Web加载器\"）\n\n根据您提供的指南，我不能凭空编造源码中没有的行为或实现细节。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：run-llama/llama_index\n\n摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。\n\n## 1. 能力坑 · 能力证据存在缺口\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Sandbox install result is missing.\n- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。\n- 建议检查：优先补证或在页面明确标记为未验证。\n- 防护动作：证据缺口未关闭前，quality gate 必须保持不可发布。\n- 证据：evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing.\n\n## 2. 能力坑 · 能力判断依赖假设\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:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 6. 维护坑 · 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:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | release_recency=unknown\n\n\n",
"markdown_key": "llama-index",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:560704231",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/run-llama/llama_index"
},
{
"evidence_id": "art_7f645de137d340bf894a430f3616fd1b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/run-llama/llama_index#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "llama_index 说明书",
"toc": [
"https://github.com/run-llama/llama_index 项目说明书",
"目录",
"LlamaIndex 简介",
"概述",
"核心架构",
"核心概念",
"数据读取器（Readers）",
"LLM 集成",
"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": true,
"repo_commit": "b4a235dec21e5a08bc0f08f617318f417da4e6a8",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/DOCS_README.md",
"docs/scripts/prepare_for_build.py",
"docs/examples/index.md",
"docs/api_reference/pyproject.toml",
"docs/api_reference/mkdocs.yml",
"docs/src/content/docs/framework/index.md",
"docs/src/content/docs/framework/CONTRIBUTING.md",
"docs/src/content/docs/framework/_meta.yml",
"docs/src/content/docs/framework/CHANGELOG.md",
"docs/src/content/docs/framework/llama_cloud/index.md",
"docs/src/content/docs/framework/llama_cloud/llama_parse.md",
"docs/src/content/docs/framework/llama_cloud/_meta.yml",
"docs/src/content/docs/framework/use_cases/chatbots.md",
"docs/src/content/docs/framework/use_cases/index.md",
"docs/src/content/docs/framework/use_cases/prompting.md",
"docs/src/content/docs/framework/use_cases/tables_charts.md",
"docs/src/content/docs/framework/use_cases/querying_csvs.md",
"docs/src/content/docs/framework/use_cases/multimodal.md",
"docs/src/content/docs/framework/use_cases/fine_tuning.md",
"docs/src/content/docs/framework/use_cases/q_and_a.md",
"docs/src/content/docs/framework/use_cases/extraction.md",
"docs/src/content/docs/framework/use_cases/text_to_sql.md",
"docs/src/content/docs/framework/use_cases/_meta.yml",
"docs/src/content/docs/framework/use_cases/agents.md",
"docs/src/content/docs/framework/use_cases/graph_querying.md",
"docs/src/content/docs/framework/understanding/privacy.md",
"docs/src/content/docs/framework/understanding/using_llms.mdx",
"docs/src/content/docs/framework/understanding/index.mdx",
"docs/src/content/docs/framework/understanding/_meta.yml",
"docs/src/content/docs/framework/javascript/llms_example.js",
"docs/src/content/docs/framework/javascript/algolia.js",
"docs/src/content/docs/framework/javascript/runllm.js",
"docs/src/content/docs/framework/javascript/_meta.yml",
"docs/src/content/docs/framework/optimizing/custom_modules.md",
"docs/src/content/docs/framework/optimizing/production_rag.md",
"docs/src/content/docs/framework/optimizing/building_rag_from_scratch.md",
"docs/src/content/docs/framework/optimizing/_meta.yml"
],
"repo_inspection_verified": true,
"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": "# llama_index - Doramagic AI Context Pack\n\n> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。\n\n## 项目\n\n- canonical_name: `run-llama/llama_index`\n- capability: LlamaIndex is the leading document agent and OCR platform\n- expected_user_outcome: LlamaIndex is the leading document agent and OCR platform\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- **LlamaIndex 简介**：importance `high`\n - source_paths: README.md, llama-index-core/llama_index/core/__init__.py, llama-index-core/README.md\n- **快速入门指南**：importance `high`\n - source_paths: docs/examples/vector_stores/SimpleIndexDemo.ipynb, docs/src/content/docs/framework/getting_started/installation.mdx, docs/src/content/docs/framework/getting_started/starter_example.mdx\n- **系统架构**：importance `high`\n - source_paths: llama-index-core/llama_index/core/indices/base.py, llama-index-core/llama_index/core/query_engine/retriever_query_engine.py, llama-index-core/llama_index/core/storage/storage_context.py\n- **核心组件详解**：importance `high`\n - source_paths: llama-index-core/llama_index/core/schema.py, llama-index-core/llama_index/core/indices/vector_store/base.py, llama-index-core/llama_index/core/indices/property_graph/base.py, llama-index-core/llama_index/core/indices/knowledge_graph/base.py, llama-index-core/llama_index/core/response_synthesizers/base.py\n- **数据摄取流程**：importance `high`\n - source_paths: llama-index-core/llama_index/core/ingestion/pipeline.py, llama-index-core/llama_index/core/readers/base.py, llama-index-core/llama_index/core/readers/file/base.py, llama-index-core/llama_index/core/ingestion/transformations.py\n- **节点解析器**：importance `medium`\n - source_paths: llama-index-core/llama_index/core/node_parser/text/sentence.py, llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py, llama-index-core/llama_index/core/node_parser/relational/markdown_element.py, llama-index-core/llama_index/core/node_parser/interface.py\n- **存储层架构**：importance `high`\n - source_paths: llama-index-core/llama_index/core/storage/storage_context.py, llama-index-core/llama_index/core/vector_stores/types.py, llama-index-core/llama_index/core/storage/docstore/types.py, llama-index-core/llama_index/core/storage/chat_store/base.py\n- **智能体系统**：importance `high`\n - source_paths: llama-index-core/llama_index/core/agent/react/formatter.py, llama-index-core/llama_index/core/agent/workflow/base_agent.py, llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py, llama-index-core/llama_index/core/tools/function_tool.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `b4a235dec21e5a08bc0f08f617318f417da4e6a8`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/DOCS_README.md`, `docs/scripts/prepare_for_build.py`, `docs/examples/index.md`, `docs/api_reference/pyproject.toml`, `docs/api_reference/mkdocs.yml`, `docs/src/content/docs/framework/index.md`, `docs/src/content/docs/framework/CONTRIBUTING.md`, `docs/src/content/docs/framework/_meta.yml`, `docs/src/content/docs/framework/CHANGELOG.md`, `docs/src/content/docs/framework/llama_cloud/index.md`, `docs/src/content/docs/framework/llama_cloud/llama_parse.md`, `docs/src/content/docs/framework/llama_cloud/_meta.yml`, `docs/src/content/docs/framework/use_cases/chatbots.md`, `docs/src/content/docs/framework/use_cases/index.md`, `docs/src/content/docs/framework/use_cases/prompting.md`, `docs/src/content/docs/framework/use_cases/tables_charts.md`, `docs/src/content/docs/framework/use_cases/querying_csvs.md`\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: Sandbox install result is missing.\n- Host AI rule: 优先补证或在页面明确标记为未验证。\n- Why it matters: 缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。\n- Evidence: evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\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:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\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:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 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:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | 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项目：run-llama/llama_index\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- 能力证据存在缺口（high）：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。 建议检查：优先补证或在页面明确标记为未验证。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\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": "# https://github.com/run-llama/llama_index 项目说明书\n\n生成时间：2026-05-11 04:42:04 UTC\n\n## 目录\n\n- [LlamaIndex 简介](#introduction)\n- [快速入门指南](#quickstart)\n- [系统架构](#system_architecture)\n- [核心组件详解](#core_components)\n- [数据摄取流程](#data_ingestion)\n- [节点解析器](#node_parsing)\n- [存储层架构](#storage_layer)\n- [智能体系统](#agent_system)\n- [工作流引擎](#workflow_engine)\n- [查询引擎](#query_engine)\n\n\n\n## LlamaIndex 简介\n\n### 相关页面\n\n相关主题：[快速入门指南](#quickstart), [系统架构](#system_architecture), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/run-llama/llama_index/blob/main/README.md)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)\n- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n- [llama-index-integrations/llms/llama-index-llms-contextual/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-contextual/README.md)\n- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n \n\n# LlamaIndex 简介\n\n## 概述\n\nLlamaIndex 是一个用于构建 **LLM（大型语言模型）应用** 的数据框架，官方仓库位于 [run-llama/llama_index](https://github.com/run-llama/llama_index)。该框架的核心设计理念是简化 LLM 与私有或特定领域数据的连接过程，使开发者能够快速构建检索增强生成（RAG）系统、问答应用和数据索引工具。\n\nLlamaIndex 提供了丰富的数据连接器（Readers）、索引构建能力、检索和查询引擎，以及与多种 LLM 提供商的无缝集成。资料来源：[README.md:1]()\n\n## 核心架构\n\nLlamaIndex 的整体架构可分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[数据源] --> B[Readers 数据读取层]\n B --> C[Documents 文档对象]\n C --> D[Index 索引层]\n D --> E[Retrievers 检索层]\n E --> F[Query Engine 查询引擎]\n F --> G[LLM 输出层]\n \n B --> B1[Web Readers]\n B --> B2[File Readers]\n B --> B3[API Readers]\n B --> B4[Database Readers]\n \n G --> G1[OpenAI]\n G --> G2[Ollama]\n G --> G3[LM Studio]\n G --> G4[ModelScope]\n```\n\n### 模块层次说明\n\n| 层次 | 功能描述 | 核心组件 |\n|------|----------|----------|\n| **数据读取层** | 从各类数据源加载原始数据 | RemoteDepthReader, DoclingReader, WikipediaReader 等 |\n| **文档对象层** | 将数据转换为标准化的 Document 对象 | Document, MediaResource |\n| **索引层** | 构建可检索的向量或结构化索引 | VectorStoreIndex, SummaryIndex |\n| **检索层** | 根据查询获取相关文档 | Retriever, similarity_top_k 参数 |\n| **查询引擎层** | 执行检索并调用 LLM 生成答案 | QueryEngine, as_query_engine() |\n| **LLM 输出层** | 与各类 LLM 提供商集成 | Contextual, LMStudio, Ollama 等 |\n\n## 核心概念\n\n### Document 文档对象\n\nDocument 是 LlamaIndex 中的核心数据单元，用于表示任意文本或多媒体内容。\n\n```python\nfrom llama_index.core.schema import Document, MediaResource\n\ndoc = Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"这是一段示例文本内容\"\n ),\n)\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:18-25]()\n\n### Index 索引\n\n索引是将文档组织成可高效检索结构的关键组件。最常用的是 VectorStoreIndex，它将文档转换为向量表示进行语义检索。\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\n\nindex = VectaraIndex.from_documents(docs)\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:35]()\n\n## 数据读取器（Readers）\n\nLlamaIndex 提供了丰富的读取器集成，支持从多种数据源加载数据。\n\n### Web 数据读取器\n\n| 读取器名称 | 功能描述 | 依赖库 |\n|-----------|----------|--------|\n| WholeSiteReader | 整站爬取，支持深度递归 | 内置 |\n| NewsArticleReader | 新闻文章解析 | newspaper3k |\n| UnstructuredURLLoader | URL 内容提取 | unstructured |\n| ReadabilityWebPageReader | 网页主内容提取 | readability |\n| MainContentExtractorReader | 主内容提取 | main_content_extractor |\n| TrafilaturaWebReader | 网页内容解析 | trafilatura |\n\n使用示例：\n\n```python\nfrom llama_index.readers.web import NewsArticleReader\n\nreader = NewsArticleReader(use_nlp=False)\ndocuments = reader.load_data(\n urls=[\"https://www.example.com/news/article.html\"]\n)\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md:15-20]()\n\n### 整站爬取功能\n\nWholeSiteReader 支持从指定 URL 开始，按深度递归爬取整个网站的内容：\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:10-20]()\n\n### 文档解析读取器\n\n**Docling Reader** 支持从 PDF、DOCX、HTML 等格式提取内容：\n\n```python\nfrom llama_index.readers.docling import DoclingReader\n\nreader = DoclingReader()\ndocs = reader.load_data(file_path=\"https://arxiv.org/pdf/2408.09869\")\n```\n\n支持的文件格式：\n\n| 格式 | 支持情况 | 导出类型 |\n|------|----------|----------|\n| PDF | ✅ 完整支持 | Markdown / JSON |\n| DOCX | ✅ 完整支持 | Markdown / JSON |\n| HTML | ✅ 完整支持 | Markdown / JSON |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md:15-35]()\n\n### Wikipedia 读取器\n\n```python\nfrom llama_index.readers.wikipedia import WikipediaReader\n\nreader = WikipediaReader()\ndocuments = reader.load_data(pages=[\"Page Title 1\", \"Page Title 2\"])\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-wikipedia/README.md:20-30]()\n\n## LLM 集成\n\n### 主要 LLM 提供商\n\n| 提供商 | 包名 | 特点 |\n|--------|------|------|\n| Contextual | llama-index-llms-contextual | 上下文感知的 LLM |\n| LM Studio | llama-index-llms-lmstudio | 本地模型服务 |\n| ModelScope | llama-index-llms-modelscope | 阿里魔搭模型 |\n| Ollama | 内置支持 | 本地 LLM 运行 |\n\n### Contextual LLM 示例\n\n```python\nfrom llama_index.llms.contextual import Contextual\n\nllm = Contextual(model=\"contextual-clm\", api_key=\"your_api_key\")\nresponse = llm.complete(\"Explain the importance of Grounded Language Models.\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-contextual/README.md:15-20]()\n\n### LM Studio 集成\n\n```python\nfrom llama_index.llms.lmstudio import LMStudio\n\nllm = LMStudio(\n model_name=\"Hermes-2-Pro-Llama-3-8B\",\n base_url=\"http://localhost:1234/v1\",\n temperature=0.7,\n)\n\nmessages = [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=\"You are an expert AI assistant.\",\n ),\n ChatMessage(\n role=MessageRole.USER,\n content=\"What is the significance of the number 42?\",\n ),\n]\n\nresponse = llm.chat(messages=messages)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-lmstudio/README.md:15-35]()\n\n## 向量嵌入集成\n\n### Ollama 嵌入模型\n\nOllama 提供了多个嵌入模型选项：\n\n| 模型名称 | 用途 | 特点 |\n|----------|------|------|\n| nomic-embed-text | 通用嵌入 | 通用目的 |\n| embeddinggemma | 文本嵌入 | Google Gemma 系列 |\n| mxbai-embed-large | 高质量嵌入 | 大规模模型 |\n\n安装与使用：\n\n```bash\nollama pull nomic-embed-text\n```\n\n```python\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://localhost:11434\",\n)\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:5-30]()\n\n### ModelScope 嵌入\n\n```python\nfrom llama_index.embeddings.modelscope.base import ModelScopeEmbedding\n\nmodel = ModelScopeEmbedding(\n model_name=\"iic/nlp_gte_sentence-embedding_chinese-base\",\n model_revision=\"master\",\n)\n\nrsp = model.get_query_embedding(\"你好，你是谁？\")\nrsp = model.get_text_embedding_batch([\"你好\", \"我是学生\"])\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md:15-35]()\n\n## 检索与查询流程\n\n### 标准 RAG 工作流\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Query Engine]\n B --> C[Retriever 检索]\n C --> D[向量相似度匹配]\n D --> E[相关文档]\n E --> F[LLM 生成]\n F --> G[最终回答]\n```\n\n### 检索器使用\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\n\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"How will users feel about this new tool?\")\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:45-50]()\n\n### 查询引擎使用\n\n```python\nquery_engine = index.as_query_engine()\nresults = query_engine.query(\"用户对工具的感受如何？\")\n```\n\n## 完整使用示例\n\n以下是一个典型的 LlamaIndex 完整使用流程：\n\n```mermaid\ngraph TD\n A[加载数据] --> B[创建索引]\n B --> C[获取检索器]\n C --> D{使用方式}\n D -->|直接检索| E[Retriever]\n D -->|生成回答| F[Query Engine]\n E --> G[相关文档列表]\n F --> H[LLM 回答]\n```\n\n完整代码示例：\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.web import NewsArticleReader\n\n# 1. 加载数据\nreader = NewsArticleReader(use_nlp=False)\ndocuments = reader.load_data(urls=[\"https://example.com/article.html\"])\n\n# 2. 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 3. 获取检索器\nretriever = index.as_retriever(similarity_top_k=5)\n\n# 4. 检索相关文档\nresults = retriever.retrieve(\"查询内容\")\n\n# 或使用查询引擎获取 LLM 回答\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"查询内容\")\n```\n\n## 特性总结\n\n### LlamaIndex 核心能力矩阵\n\n| 能力维度 | 支持情况 | 说明 |\n|----------|----------|------|\n| 多数据源接入 | ✅ | Web、文件、API、数据库等 |\n| 多格式文档解析 | ✅ | PDF、DOCX、HTML、Markdown 等 |\n| 多种 LLM 集成 | ✅ | OpenAI、Ollama、LM Studio 等 |\n| 向量嵌入支持 | ✅ | 本地模型、云服务多种选择 |\n| RAG 检索增强 | ✅ | 内置检索和查询引擎 |\n| 可扩展架构 | ✅ | 模块化设计，支持自定义组件 |\n\n## 引用信息\n\n如需在学术论文中引用 LlamaIndex，请使用以下格式：\n\n```\n@software{Liu_LlamaIndex_2022,\nauthor = {Liu, Jerry},\ndoi = {10.5281/zenodo.1234},\nmonth = {11},\ntitle = {{LlamaIndex}},\nurl = {https://github.com/jerryjliu/llama_index},\nyear = {2022}\n}\n```\n\n资料来源：[README.md:95-102]()\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[LlamaIndex 简介](#introduction), [系统架构](#system_architecture), [数据摄取流程](#data_ingestion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md)\n- [llama-index-integrations/llms/llama-index-llms-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-ollama/README.md)\n- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n- [llama-index-integrations/llms/llama-index-llms-konko/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-konko/README.md)\n \n\n# 快速入门指南\n\n## 概述\n\nLlamaIndex 是一个强大的大语言模型（LLM）数据框架，旨在帮助开发者构建基于私有知识和增强语言模型的应用程序。本指南将引导您从零开始，快速掌握 LlamaIndex 的核心功能和使用方法。\n\nLlamaIndex 的主要应用场景包括：\n\n- **文档问答系统**：基于私有文档库构建智能问答应用\n- **语义搜索**：使用向量数据库实现高效的信息检索\n- **代理（Agent）应用**：构建能够访问多种工具的 AI 代理\n- **数据摄取与索引**：支持从多种数据源加载和索引文档\n\n## 安装\n\n### 基本安装\n\n使用 pip 安装 LlamaIndex 核心包：\n\n```bash\npip install llama-index\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()\n\n### 集成包安装\n\n根据您的具体需求，可以安装不同的集成包：\n\n| 集成类型 | 包名称 | 用途 |\n|---------|--------|------|\n| Web 读取器 | `llama-index-readers-web` | 从网页加载内容 |\n| Ollama LLM | `llama-index-llms-ollama` | 本地 LLM 支持 |\n| Ollama 嵌入 | `llama-index-embeddings-ollama` | 本地嵌入模型 |\n| Vectara 索引 | `llama-index-indices-managed-vectara` | Vectara 云索引 |\n| Konko LLM | `llama-index-llms-konko` | Konko API 支持 |\n| LangChain 集成 | 随上述包自动安装 | 与 LangChain 代理集成 |\n\n安装示例：\n\n```bash\npip install llama-index-llms-ollama\npip install llama-index-readers-web\npip install llama-index-indices-managed-vectara\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n## 核心概念\n\n### 数据流程架构\n\n```mermaid\ngraph TD\n A[数据源] --> B[Document 文档]\n B --> C[Node 节点]\n C --> D[Index 索引]\n D --> E[Retriever 检索器]\n E --> F[Query Engine 查询引擎]\n F --> G[Response 响应]\n \n H[LLM] --> F\n```\n\nLlamaIndex 的核心数据流程包含以下关键组件：\n\n1. **Document（文档）**：表示要索引的原始数据，可以是文本、HTML、PDF 等格式\n2. **Node（节点）**：将 Document 分割后的数据块，便于高效检索\n3. **Index（索引）**：存储节点的数据结构，支持快速相似度搜索\n4. **Retriever（检索器）**：从索引中获取相关节点\n5. **Query Engine（查询引擎）**：整合检索和 LLM 生成答案\n\n### 文档加载\n\nLlamaIndex 支持多种数据源加载器：\n\n| 加载器 | 包名 | 数据源 |\n|-------|------|--------|\n| SimpleDirectoryReader | 核心包 | 本地文件系统 |\n| WholeSiteReader | llama-index-readers-web | 整个网站 |\n| ReadabilityWebPageReader | llama-index-readers-web | 单个网页（可读性优化） |\n| NewsArticleReader | llama-index-readers-web | 新闻文章 |\n| RemoteDepthReader | llama-index-readers-remote-depth | 远程 URL 层级 |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()\n\n## 快速示例\n\n### 基础文档问答\n\n以下示例展示如何使用 LlamaIndex 构建最基本的文档问答系统：\n\n```python\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\n# 加载本地文档\ndocuments = SimpleDirectoryReader(\"data\").load_data()\n\n# 创建向量索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 创建查询引擎\nquery_engine = index.as_query_engine()\n\n# 执行查询\nresponse = query_engine.query(\"作者在成长过程中做了些什么？\")\nprint(response)\n```\n\n这是 LlamaIndex 最基本的用法模式：加载文档 → 创建索引 → 查询。\n\n### 使用 Web 读取器\n\n#### 单页面读取\n\n```python\nfrom llama_index.readers.web import ReadabilityWebPageReader\n\nloader = ReadabilityWebPageReader()\ndocuments = loader.load_data(\n url=\"https://example.com/article\"\n)\n\nindex = VectorStoreIndex.from_documents(documents)\nprint(index.query(\"这篇文文章的主要内容是什么？\"))\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()\n\n#### 全站抓取\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\n# 初始化抓取器\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\n# 从基础 URL 开始抓取\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n\nindex = VectorStoreIndex.from_documents(documents)\nindex.query(\"这个网站使用什么语言？\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()\n\n### 使用本地 LLM（Ollama）\n\n```python\nfrom llama_index.llms.ollama import Ollama\n\n# 初始化 Ollama LLM\nllm = Ollama(model=\"llama3.1:latest\", request_timeout=120.0)\n\n# 生成补全\nresp = llm.complete(\"Paul Graham 是谁？\")\nprint(resp)\n\n# 使用聊天接口\nfrom llama_index.core.llms import ChatMessage\n\nmessages = [\n ChatMessage(\n role=\"system\", \n content=\"你是一个友好的助手\"\n ),\n ChatMessage(\n role=\"user\", \n content=\"解释一下大爆炸理论\"\n ),\n]\n\nresp = llm.chat(messages)\nprint(resp)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n### 使用云索引服务（Vectara）\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\nfrom llama_index.core.schema import Document, MediaResource\nimport os\n\n# 设置环境变量\nos.environ[\"VECTARA_API_KEY\"] = \"\"\nos.environ[\"VECTARA_CORPUS_KEY\"] = \"\"\n\n# 创建文档\ndocs = [\n Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"这是 Vectara 与 LlamaIndex 集成的测试文本。\"\n ),\n ),\n]\n\n# 创建索引并添加文档\nindex = VectaraIndex.from_documents(docs)\n\n# 检索文档\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"用户体验如何？\")\nprint(results[0])\n\n# 作为查询引擎使用\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"总结主要内容\")\n```\n\n资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()\n\n## 与 LangChain 集成\n\nLlamaIndex 可以作为工具集成到 LangChain 代理中：\n\n```python\nfrom llama_index.core import VectorStoreIndex, download_loader\nfrom langchain.agents import initialize_agent, Tool\nfrom langchain.llms import OpenAI\nfrom langchain.chains.conversation.memory import ConversationBufferMemory\n\nfrom llama_index.readers.web import ReadabilityWebPageReader\n\n# 加载文档\nloader = ReadabilityWebPageReader()\ndocuments = loader.load_data(\n url=\"https://example.com/article\"\n)\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 定义工具\ntools = [\n Tool(\n name=\"Website Index\",\n func=lambda q: index.query(q),\n description=\"用于回答网站内容相关问题的工具。\",\n ),\n]\n\n# 初始化代理\nllm = OpenAI(temperature=0)\nmemory = ConversationBufferMemory(memory_key=\"chat_history\")\nagent_chain = initialize_agent(\n tools, llm, agent=\"zero-shot-react-description\", memory=memory\n)\n\n# 运行代理\noutput = agent_chain.run(input=\"网站的主要内容是什么？\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()\n\n## 嵌入模型配置\n\n### Ollama 嵌入\n\n```python\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://your-remote-server:11434\",\n)\n\n# 使用嵌入模型\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\ndocuments = SimpleDirectoryReader(\"data\").load_data()\nindex = VectorStoreIndex.from_documents(documents, embed_model=embed_model)\n```\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()\n\n### 可用嵌入模型\n\n| 模型 ID | 描述 | 适用场景 |\n|--------|------|---------|\n| `nomic-embed-text` | 通用嵌入模型 | 通用任务 |\n| `embeddinggemma` | Google Gemma 系列 | 高精度需求 |\n| `mxbai-embed-large` | 大型嵌入模型 | 最佳质量 |\n\n安装嵌入模型：\n\n```bash\nollama pull nomic-embed-text\n```\n\n## 完整 RAG 流程\n\n```mermaid\ngraph LR\n A[用户问题] --> B[检索]\n B --> C[向量相似度匹配]\n C --> D[相关文档片段]\n D --> E[上下文构建]\n E --> F[LLM 生成]\n F --> G[最终回答]\n \n H[(文档库)] --> I[文档加载]\n I --> J[分块处理]\n J --> K[向量编码]\n K --> C\n```\n\n完整的 RAG（检索增强生成）流程包括：\n\n| 阶段 | 组件 | 描述 |\n|-----|------|------|\n| 数据摄入 | Document Loader | 从各种来源加载文档 |\n| 处理 | Node Parser | 将文档分割成小块 |\n| 索引 | Vector Store | 存储向量表示 |\n| 检索 | Retriever | 找到相关上下文 |\n| 生成 | Query Engine + LLM | 生成最终答案 |\n\n## 常见问题\n\n### 连接错误\n\n如果遇到连接错误，请检查：\n\n1. Ollama 服务是否运行：`ollama serve`\n2. `base_url` 是否与 Ollama 服务器地址匹配\n3. 模型是否已下载：`ollama pull `\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()\n\n### 模型未找到\n\n如果出现\"模型未找到\"错误：\n\n1. 列出可用模型：`ollama list`\n2. 拉取所需模型：`ollama pull `\n3. 确认模型名称在代码中完全匹配\n\n### 超时配置\n\n默认超时时间为 30 秒，可以通过 `request_timeout` 参数调整：\n\n```python\nllm = Ollama(\n model=\"llama3.1:latest\", \n request_timeout=300.0\n)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()\n\n## 下一步\n\n掌握基础用法后，您可以深入学习以下高级主题：\n\n- **自定义检索器**：实现混合搜索策略\n- **流式响应**：实现实时生成输出\n- **回调系统**：集成 Argilla 等监控工具\n- **多模态支持**：处理图像和文本混合内容\n- **代理工具集成**：构建更复杂的 AI 代理应用\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件详解](#core_components), [数据摄取流程](#data_ingestion), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/indices/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/base.py)\n- [llama-index-core/llama_index/core/query_engine/retriever_query_engine.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py)\n- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)\n- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md)\n- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n \n\n# 系统架构\n\n## 概述\n\nLlamaIndex 是一个专为大型语言模型（LLM）应用设计的检索增强生成（RAG）框架，其系统架构围绕数据索引构建、智能查询处理和持久化存储三大核心功能展开。框架采用模块化设计，通过清晰的分层结构将数据加载、文档处理、索引管理、查询执行和存储管理解耦，同时保持各组件间的无缝协作能力。\n\nLlamaIndex 的架构设计遵循\"数据优先\"的原则，首先通过多元化的 Reader 组件从不同数据源提取内容，然后经过解析和分块处理形成结构化的 Node 对象，最终由各类 Index 索引进行组织和存储。查询阶段则通过 Query Engine 实现语义理解和信息检索的结合，为 LLM 提供准确的上下文支撑。\n\n## 核心架构组件\n\n### 索引层（Indices）\n\n索引层是 LlamaIndex 架构的核心，负责将非结构化数据转换为可高效检索的向量表示。根据应用场景的不同，框架提供了多种索引类型的实现：\n\n| 索引类型 | 用途描述 | 适用场景 |\n|---------|---------|----------|\n| VectorStoreIndex | 基于向量嵌入的语义检索 | 问答系统、内容推荐 |\n| DocumentSummaryIndex | 文档摘要索引 | 长文档快速概览 |\n| KnowledgeGraphIndex | 知识图谱索引 | 关系型问答、实体链接 |\n| TreeIndex | 树形结构索引 | 分层文档组织 |\n| KeywordTableIndex | 关键词表索引 | 精确关键词匹配 |\n\n索引架构采用基类继承设计，所有索引类型都继承自 BaseIndex 抽象基类，共享通用的索引生命周期管理接口，包括索引创建、更新、删除和持久化等核心操作。这种设计确保了索引行为的一致性，同时允许各子类根据具体需求实现特定的索引逻辑。\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[Node Parser 节点解析器]\n B --> C[Index 索引构建]\n C --> D[VectorStoreIndex 向量索引]\n C --> E[KnowledgeGraphIndex 知识图谱索引]\n C --> F[TreeIndex 树形索引]\n D --> G[Vector Store 向量存储]\n E --> H[Graph Store 图存储]\n F --> I[Document Store 文档存储]\n```\n\n资料来源：[llama-index-core/llama_index/core/indices/base.py:1-50]()\n\n### 查询引擎层（Query Engine）\n\n查询引擎层负责接收用户查询并返回相关结果。框架提供了多种查询引擎实现，其中 RetrieverQueryEngine 是最常用的实现，它将检索器（Retriever）与 LLM 相结合，实现语义理解与信息检索的闭环处理。\n\nRetrieverQueryEngine 的核心工作流程包括：首先接收自然语言查询，然后调用底层的 Retriever 从索引中检索相关节点，接着将检索结果与原始查询组装为 Prompt 提交给 LLM 进行答案生成。这种设计实现了检索与生成的分离，使得用户可以灵活切换不同的检索策略和 LLM 模型。\n\n```mermaid\ngraph LR\n A[User Query 用户查询] --> B[Retriever 检索器]\n B --> C[Retrieved Nodes 检索节点]\n C --> D[Response Synthesizer 响应合成器]\n D --> E[LLM 大语言模型]\n E --> F[Final Response 最终响应]\n```\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py:1-80]()\n\n### 存储层（Storage）\n\n存储层负责管理索引数据和文档的持久化。StorageContext 是存储架构的核心抽象，它整合了三种存储组件：DocStore（文档存储）、IndexStore（索引存储）和 VectorStore（向量存储）。这种三分层设计使得不同类型的数据可以选用最适合的存储后端。\n\n| 存储组件 | 存储内容 | 支持的后端 |\n|---------|---------|------------|\n| DocStore | 原始文档和节点数据 | MongoDB、Redis、SimpleDocumentStore |\n| IndexStore | 索引元数据 | MongoDB、Redis、SimpleIndexStore |\n| VectorStore | 向量嵌入数据 | Chroma、Pinecone、Weaviate、Milvus |\n\nStorageContext 提供了统一的存储接口抽象，屏蔽了底层存储实现细节，使得应用程序可以在不同存储后端之间灵活切换而无需修改业务逻辑代码。\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py:1-100]()\n\n## 数据加载与处理\n\n### Reader 集成系统\n\nLlamaIndex 的 Reader 系统提供了从多样化数据源加载内容的能力，这是实现端到端 RAG 流程的数据入口。Reader 架构采用统一接口设计，所有 Reader 都实现 BaseReader 接口，提供标准化的 `load_data()` 方法。\n\n当前框架支持的主要 Reader 类型及其数据源：\n\n| Reader 类型 | 数据源 | 用途 |\n|------------|--------|------|\n| NewsArticleReader | 新闻网站 | 抓取 CNBC、The Verge 等新闻内容 |\n| TrafilaturaWebReader | 通用网页 | 使用 trafilatura 库提取网页正文 |\n| MainContentExtractorReader | 静态网站 | 提取网页主要内容区域 |\n| UnstructuredURLLoader | 任意网页 | 使用 Unstructured.io 解析 HTML |\n| ReadabilityWebPageReader | 新闻文章 | 使用 Mozilla Readability 算法 |\n| WholeSiteReader | 整站爬取 | 按深度递归爬取整个网站 |\n| WikipediaReader | Wikipedia | 读取 Wikipedia 条目内容 |\n| SemanticScholarReader | 学术论文 | 获取 Semantic Scholar 论文数据 |\n| DoclingReader | PDF/DOCX/HTML | 使用 Docling 提取复杂文档 |\n| BoxReader | Box 云存储 | 读取 Box 中的文件和文件夹 |\n| WordPressReader | WordPress 博客 | 通过 WP REST API 获取内容 |\n\n这种多元化的 Reader 设计确保了 LlamaIndex 可以接入几乎所有常见的数据源，从网页内容到企业文档，从学术论文到云存储文件，构建完整的 RAG 数据管道。\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md]()\n资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md]()\n\n### 文档处理流程\n\n文档从原始数据到可索引状态的转换过程涉及多个处理阶段：\n\n```mermaid\ngraph TD\n A[Raw Data 原始数据] --> B[Reader 读取器]\n B --> C[Document 对象]\n C --> D[Node Parser 节点解析器]\n D --> E[TextNode / ImageNode]\n E --> F[Embedding Model 嵌入模型]\n F --> G[Indexed Nodes 索引节点]\n G --> H[VectorStoreIndex]\n```\n\nNode Parser 负责将 Document 拆分为更小的语义单元（Node），这个过程支持多种策略：\n\n- **TokenTextSplitter**：基于 token 数量的文本分块\n- **SentenceSplitter**：基于句子边界的分块\n- **RecursiveCharacterTextSplitter**：递归字符分块，优先保持段落完整性\n\n## 查询处理流程\n\n### 检索与生成分离\n\nLlamaIndex 架构的核心设计理念之一是检索与生成的分离。这种设计带来了多重优势：首先，允许独立优化检索和生成两个环节；其次，支持多种检索策略的灵活组合；第三，便于实现缓存和结果复用。\n\n```mermaid\ngraph TD\n A[Query 输入查询] --> B[Query Transform 查询变换]\n B --> C[Embedding 嵌入生成]\n C --> D[Vector Search 向量搜索]\n D --> E[Top-K Retrieval Top-K 检索]\n E --> F[Node Postprocessors 节点后处理器]\n F --> G[Context Assembly 上下文组装]\n G --> H[LLM Response Generation LLM 响应生成]\n H --> I[Response 输出响应]\n```\n\n### 查询引擎类型\n\n| 引擎类型 | 描述 | 核心特性 |\n|---------|------|----------|\n| RetrieverQueryEngine | 标准检索引擎 | 基础 RAG 流程 |\n| CitationQueryEngine | 引用查询引擎 | 支持答案溯源 |\n| MultiStepQueryEngine | 多步查询引擎 | 处理复杂多跳问题 |\n| SubQuestionQueryEngine | 子问题引擎 | 将复杂问题分解 |\n\nCitationQueryEngine 是一个重要的扩展，它不仅返回答案，还提供答案引用的来源信息，使得用户可以验证和追溯生成内容的准确性。这对于构建可信赖的 RAG 应用至关重要。\n\n## 嵌入与向量化\n\n### 嵌入模型集成\n\nLlamaIndex 的嵌入系统采用插件化设计，通过抽象的 BaseEmbedding 接口支持多种嵌入模型后端。当前支持的嵌入服务包括：\n\n- **OpenAI Embeddings**：OpenAI 的 text-embedding-ada-002 等模型\n- **Ollama Embeddings**：本地运行的 Ollama 模型，如 nomic-embed-text\n- **ModelScope Embeddings**：阿里魔搭平台的嵌入模型，如 nlp_gte_sentence-embedding_chinese-base\n- **HuggingFace Embeddings**：HuggingFace 生态的各种嵌入模型\n\n这种模块化设计允许开发者根据数据语言、应用场景和性能要求选择最合适的嵌入模型，同时保持上层索引和查询逻辑的稳定性。\n\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md]()\n资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md]()\n\n## 服务架构\n\n### 服务上下文（ServiceContext）\n\nServiceContext 是 LlamaIndex 的服务配置中心，它聚合了 LLM、嵌入模型、提示模板、回调处理器等运行时组件。通过 ServiceContext，开发者可以一次性配置好整个 RAG 流程所需的全部服务组件。\n\n```mermaid\ngraph TD\n A[ServiceContext] --> B[LLM 大语言模型]\n A --> C[Embedding Model 嵌入模型]\n A --> D[Node Parser 节点解析器]\n A --> E[Prompt Template 提示模板]\n A --> F[Callback Manager 回调管理器]\n G[Query Pipeline] --> A\n H[Index Construction] --> A\n```\n\n### 回调系统\n\nLlamaIndex 提供了全面的回调机制（Callback System），覆盖索引构建、查询执行、检索过程等关键节点。通过 CallbackManager，应用可以：\n\n- 记录执行时间消耗\n- 追踪 Token 使用量\n- 监控检索结果质量\n- 集成第三方监控服务\n\n## 工作流示意\n\n### 端到端 RAG 流程\n\n```mermaid\ngraph LR\n A[数据源] -->|Reader| B[Documents]\n B -->|Node Parser| C[Nodes]\n C -->|Embedding| D[Vector Index]\n D -->|Storage| E[Persist Storage]\n \n F[User Query] -->|Embedding| G[Retrieve]\n G -->|Top-K| H[Relevant Nodes]\n H -->|Context| I[LLM]\n I -->|Generate| J[Response]\n```\n\n## 扩展集成\n\n### 工具系统（Tools）\n\nLlamaIndex 的工具系统允许将索引和查询能力封装为可被 Agent 调用的工具。通过 Tool 接口，开发者可以创建自定义工具，暴露给 LangChain 等 Agent 框架使用。例如，Moss 工具提供了向量搜索能力，支持混合搜索（关键词 + 语义）和可配置的排名参数。\n\n| 工具名称 | 功能描述 | 关键参数 |\n|---------|---------|----------|\n| Moss | 混合向量搜索 | top_k, alpha, model_id |\n| Brightdata | 网络数据采集 | search_engine, web_data_feed |\n| Wikipedia | 维基百科查询 | pages |\n\n### 外部服务集成\n\nLlamaIndex 与多种外部服务保持深度集成，包括向量数据库（Chroma、Milvus、Pinecone）、云存储（Box、S3）、搜索服务（Brightdata）等。这种集成通过统一抽象层实现，确保了核心架构的稳定性同时提供了丰富的生态扩展能力。\n\n## 总结\n\nLlamaIndex 的系统架构体现了现代 LLM 应用框架的设计原则：**模块化、可扩展、关注点分离**。从数据加载到索引构建，从查询处理到响应生成，每个环节都被设计为可独立配置和替换的组件。这种架构使得开发者可以灵活应对不同的应用场景需求，同时享受框架提供的开箱即用功能。随着生态系统的持续发展，LlamaIndex 正在成为构建生产级 RAG 应用的首选框架之一。\n\n---\n\n\n\n## 核心组件详解\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [存储层架构](#storage_layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/schema.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/schema.py)\n- [llama-index-core/llama_index/core/indices/vector_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)\n- [llama-index-core/llama_index/core/indices/property_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/property_graph/base.py)\n- [llama-index-core/llama_index/core/indices/knowledge_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/knowledge_graph/base.py)\n- [llama-index-core/llama_index/core/response_synthesizers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/response_synthesizers/base.py)\n \n\n# 核心组件详解\n\n## 概述\n\nLlamaIndex 是一个强大的大语言模型应用框架，其核心组件构成了构建高级检索增强生成（RAG）系统的基础设施。本文档深入剖析 LlamaIndex 的核心组件体系，包括数据模型、索引类型、检索引擎和响应合成器等关键模块。这些组件协同工作，为开发者提供了从文档处理到智能问答的完整技术栈。\n\nLlamaIndex 的设计理念强调模块化和可扩展性，每个核心组件都遵循统一的接口规范，使得开发者能够灵活地组合和定制系统行为。核心组件之间的关系可以用下图表示：\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[Node 节点]\n B --> C[BaseIndex 索引基类]\n C --> D[VectorStoreIndex 向量索引]\n C --> E[PropertyGraphIndex 属性图索引]\n C --> F[KnowledgeGraphIndex 知识图谱索引]\n D --> G[Retriever 检索器]\n E --> G\n F --> G\n G --> H[ResponseSynthesizer 响应合成器]\n H --> I[Response 响应]\n```\n\n## 数据模型体系\n\n### Document 文档类\n\nDocument 是 LlamaIndex 中表示文档数据的基础单元，封装了原始文本内容和元数据信息。每个 Document 对象包含文本资源和关联的元数据字典，支持灵活的数据存储和检索需求。\n\n```mermaid\nclassDiagram\n class Document {\n +id_: str\n +text_resource: TextResource\n +metadata: Dict[str, Any]\n +embedding: Optional[List[float]]\n +embedding_strategy: Optional[EmbeddingStrategy]\n +__init__(...)\n +to_langchain_document(): langchain Document\n +to_openai_message(): Dict\n +get_content(metadata_mode: MetadataMode): str\n }\n \n class TextResource {\n +text: Optional[str]\n +relationships: Optional[Dict[RelationshipType, List[str]]]\n }\n \n Document *-- TextResource\n```\n\nDocument 类提供了丰富的属性和方法，支持与外部系统（如 LangChain）的无缝集成。text_resource 属性采用组合模式，包含实际文本内容和关系信息。metadata 字典允许存储任意键值对形式的元数据，便于后续检索和过滤。\n\n文档的创建和使用示例：\n\n```python\nfrom llama_index.core.schema import Document, TextResource, MediaResource\n\n# 基础文档创建\ndoc = Document(\n id_=\"doc-001\",\n text_resource=MediaResource(text=\"这是文档的文本内容\"),\n metadata={\"source\": \"example.txt\", \"author\": \"张三\"}\n)\n\n# 获取文档内容\ncontent = doc.get_content(metadata_mode=MetadataMode.ALL)\n```\n\n### Node 节点类\n\nNode 是 Document 的细粒度表示，代表文档经过分块处理后的最小语义单元。Node 继承自 Document，并增加了关联关系和位置信息，用于维护文档结构的层级关系。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id_` | str | 节点唯一标识符 |\n| `text_resource` | TextResource | 文本资源对象 |\n| `metadata` | Dict[str, Any] | 元数据字典 |\n| `relationships` | Dict[RelationshipType, NodeRelationship] | 关联关系映射 |\n| `metadata_seperator` | str | 元数据分隔符 |\n\nNode 的关系类型通过 RelationshipType 枚举定义，主要包括：\n\n- `SOURCE`：指向源文档的关系\n- `PREVIOUS`：指向前一个兄弟节点\n- `NEXT`：指向后一个兄弟节点\n- `PARENT`：指向父节点\n- `CHILD`：指向子节点列表\n\n```python\nfrom llama_index.core.schema import NodeRelationship, RelatedNode\n\n# 创建具有父子关系的节点\nchild_node = TextNode(\n text=\"子节点内容\",\n relationships={\n NodeRelationship.PARENT: RelatedNode(node_id=\"parent-node-id\")\n }\n)\n```\n\n## 索引系统\n\n### VectorStoreIndex 向量存储索引\n\nVectorStoreIndex 是 LlamaIndex 最核心的索引实现，基于向量相似度检索实现高效的语义搜索功能。该索引将文档转换为向量表示，并存储在向量数据库中，支持大规模数据的快速相似度查询。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[QueryEngine 查询引擎]\n B --> C[Retriever 检索器]\n C --> D[BaseRetriever 基类]\n D --> E[VectorRetriever 向量检索器]\n E --> F[VectorStore 向量存储]\n F --> G[相似向量节点]\n G --> H[ResponseSynthesizer]\n H --> I[最终响应]\n \n style F fill:#e1f5fe\n style E fill:#fff3e0\n```\n\nVectorStoreIndex 的核心架构包含以下层次：\n\n#### 索引构建流程\n\n索引的构建过程涉及文档解析、节点分割、向量计算和存储等步骤。以下是索引创建的标准流程：\n\n```python\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\n\n# 加载文档\ndocuments = SimpleDirectoryReader(\"./data\").load_data()\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(documents)\n\n# 获取查询引擎\nquery_engine = index.as_query_engine()\n\n# 执行查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n#### 向量检索器配置\n\nVectorStoreIndex 提供了丰富的检索配置选项，开发者可以根据具体需求调整检索行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vector_store` | BasePydanticVectorStore | SimpleVectorStore | 向量存储后端 |\n| `embed_model` | BaseEmbedding | None | 嵌入模型 |\n| `llm` | Optional[LLM] | None | 大语言模型 |\n| `similarity_top_k` | int | 1 | 返回的最相似结果数量 |\n| `vector_store_kwargs` | Dict | {} | 向量存储额外参数 |\n\n```python\nfrom llama_index.core.vector_stores import PineconeVectorStore\nfrom llama_index.core import VectorStoreIndex\n\n# 使用自定义向量存储\nvector_store = PineconeVectorStore(\n pinecone_index=pinecone_index,\n embed_model=embed_model\n)\n\nindex = VectorStoreIndex.from_documents(\n documents,\n vector_store=vector_store\n)\n```\n\n#### 检索模式\n\nVectorStoreIndex 支持多种检索模式，通过 as_retriever 方法可以灵活配置：\n\n```python\n# 获取默认检索器\nretriever = index.as_retriever()\n\n# 配置检索参数\nretriever = index.as_retriever(\n vector_store_kwargs={\n \"filter\": {\"category\": \"技术文档\"},\n \"top_k\": 10\n }\n)\n```\n\n### PropertyGraphIndex 属性图索引\n\nPropertyGraphIndex 是 LlamaIndex 提供的图结构索引实现，支持构建和维护复杂的实体关系网络。与传统的平面向量索引不同，PropertyGraphIndex 能够表达实体之间的多层次语义关系。\n\n```mermaid\ngraph LR\n A[实体: LlamaIndex] -->|类型| B[框架]\n A -->|用于| C[构建]\n C -->|对象| D[RAG应用]\n E[实体: RAG] -->|代表| F[检索增强生成]\n \n style A fill:#c8e6c9\n style E fill:#c8e6c9\n style C fill:#fff9c4\n style D fill:#bbdefb\n```\n\n#### 属性图的核心概念\n\nPropertyGraphIndex 基于三元组模型表示知识，三元组由源实体、关系类型和目标实体组成。这种表示方式能够清晰地捕捉现实世界中的复杂语义关联。\n\n核心组件包括：\n\n- **Entities（实体）**：表示现实世界中的对象或概念\n- **Relations（关系）**：表示实体之间的语义关联\n- **Properties（属性）**：为实体和关系添加额外描述信息\n\n#### 创建属性图索引\n\n```python\nfrom llama_index.core.indices.property_graph import PropertyGraphIndex\n\n# 使用 LLM 从文档中提取知识图谱\nindex = PropertyGraphIndex.from_documents(\n documents,\n llm=llm,\n embed_model=embed_model\n)\n\n# 自定义关系和实体提取器\nfrom llama_index.core.indices.property_graph import SchemaLLMPathExtractor\n\nschema_extractor = SchemaLLMPathExtractor(\n llm=llm,\n schema=[\n {\"name\": \"PERSON\", \"props\": [\"name\", \"age\"]},\n {\"name\": \"ORGANIZATION\", \"props\": [\"name\", \"founded\"]}\n ]\n)\n\nindex = PropertyGraphIndex.from_documents(\n documents,\n kg_extractors=[schema_extractor]\n)\n```\n\n### KnowledgeGraphIndex 知识图谱索引\n\nKnowledgeGraphIndex 是专门用于构建知识图谱的索引类型，它利用 LLM 从非结构化文本中提取实体和关系，构建可查询的知识网络。该索引继承自 PropertyGraphIndex，提供了更高级别的抽象和更便捷的 API。\n\n```mermaid\ngraph TD\n A[Document 文档] --> B[LLM 提取器]\n B --> C[三元组抽取]\n C --> D[Entity 实体]\n C --> E[Relation 关系]\n D --> F[知识图谱存储]\n E --> F\n F --> G[检索与查询]\n \n style F fill:#f3e5f5\n```\n\n#### 知识图谱索引配置\n\nKnowledgeGraphIndex 提供了丰富的配置选项：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `storage_context` | StorageContext | 存储上下文 |\n| `llm` | LLM | 用于抽取的大语言模型 |\n| `embed_model` | BaseEmbedding | 嵌入模型 |\n| `include_reasoning` | bool | 是否包含推理信息 |\n| `max_triplets_per_chunk` | int | 每个块最多抽取的三元组数 |\n| `kg_extractors` | List[KGExtractor] | 知识图谱提取器列表 |\n\n#### 使用知识图谱进行检索\n\n```python\nfrom llama_index.core.indices.knowledge_graph import KnowledgeGraphIndex\n\n# 创建知识图谱索引\nindex = KnowledgeGraphIndex.from_documents(\n documents,\n max_triplets_per_chunk=10\n)\n\n# 获取检索器\nretriever = index.as_retriever(\n include_text=True,\n retriever_mode=\"keyword\"\n)\n\n# 获取查询引擎\nquery_engine = index.as_query_engine(\n include_text=True,\n response_mode=\"tree_summarize\"\n)\n\n# 执行查询\nresponse = query_engine.query(\"关于 LlamaIndex 的信息\")\n```\n\n## 检索器系统\n\n### Retriever 检索器架构\n\nRetriever 是 LlamaIndex 中负责从索引中获取相关上下文的组件。检索器采用统一的接口设计，使得不同检索策略可以透明地互换使用。\n\n```mermaid\nclassDiagram\n class BaseRetriever {\n <>\n +retrieve(str_or_query_bundle): List[NodeWithScore]\n }\n \n class VectorRetriever {\n +filters: Optional[MetadataFilters]\n +similarity_top_k: int\n +retrieve(): List[NodeWithScore]\n }\n \n class KnowledgeGraphRetriever {\n +retriever_mode: str\n +top_k: int\n +retrieve(): List[NodeWithScore]\n }\n \n class PropertyGraphRetriever {\n +include_text: bool\n +embed_relations: bool\n +retrieve(): List[NodeWithScore]\n }\n \n BaseRetriever <|-- VectorRetriever\n BaseRetriever <|-- KnowledgeGraphRetriever\n BaseRetriever <|-- PropertyGraphRetriever\n```\n\n### 检索器类型\n\n| 检索器类型 | 说明 | 适用场景 |\n|-----------|------|----------|\n| `VectorRetriever` | 基于向量相似度的检索 | 语义搜索、向量化索引 |\n| `KnowledgeGraphRetriever` | 知识图谱检索 | 关系型查询、实体链接 |\n| `PropertyGraphRetriever` | 属性图检索 | 复杂关系查询、图遍历 |\n| `KeywordTableRetriever` | 关键词表格检索 | 精确关键词匹配 |\n| `EnsembleRetriever` | 集成检索 | 组合多种检索策略 |\n\n### 自定义检索器\n\n开发者可以通过继承 BaseRetriever 类实现自定义检索逻辑：\n\n```python\nfrom llama_index.core.retrievers import BaseRetriever\nfrom llama_index.core.schema import NodeWithScore\n\nclass CustomRetriever(BaseRetriever):\n def __init__(self, index, threshold: float = 0.7):\n super().__init__()\n self._index = index\n self._threshold = threshold\n \n def _retrieve(self, query_bundle):\n # 自定义检索逻辑\n nodes = []\n # ... 实现检索逻辑\n return nodes\n```\n\n## 响应合成器\n\n### ResponseSynthesizer 响应合成器架构\n\nResponseSynthesizer 负责将检索到的上下文与用户查询结合，生成最终的自然语言响应。这是 RAG 系统中将检索结果转化为有用答案的关键环节。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Query Bundle]\n B --> C[ResponseSynthesizer]\n C --> D{合成模式}\n D -->|compact| E[Compact 压缩模式]\n D -->|refine| F[Refine 精炼模式]\n D -->|tree_summarize| G[Tree Summarize 树形摘要]\n D -->|simple| H[Simple 简单模式]\n \n E --> I[LLM 生成]\n F --> I\n G --> I\n H --> I\n I --> J[Response 响应]\n \n style C fill:#e8f5e9\n style I fill:#fff8e1\n style J fill:#c8e6c9\n```\n\n### 响应合成模式\n\nLlamaIndex 提供了多种响应合成策略，适用于不同的应用场景：\n\n| 合成模式 | 说明 | 特点 | 适用场景 |\n|---------|------|------|----------|\n| `simple` | 简单模式 | 一次性生成响应 | 简短回答、少量上下文 |\n| `compact` | 压缩模式 | 合并多个上下文块 | 大量检索结果 |\n| `refine` | 精炼模式 | 迭代优化响应 | 需要高质量长回答 |\n| `tree_summarize` | 树形摘要 | 分层聚合信息 | 复杂多主题查询 |\n| `generation` | 生成模式 | 仅使用 LLM 生成 | 无检索场景 |\n\n### 响应合成器配置\n\n```python\nfrom llama_index.core.response_synthesizers import (\n ResponseMode,\n get_response_synthesizer\n)\n\n# 创建响应合成器\nsynthesizer = get_response_synthesizer(\n response_mode=ResponseMode.COMPACT,\n llm=llm,\n text_qa_template=qa_prompt_template,\n summary_template=summary_prompt_template\n)\n\n# 通过查询引擎使用\nquery_engine = index.as_query_engine(\n response_synthesizer=synthesizer\n)\n```\n\n### 自定义响应合成器\n\n开发者可以通过继承 BaseSynthesizer 实现自定义合成逻辑：\n\n```python\nfrom llama_index.core.response_synthesizers import BaseSynthesizer\n\nclass CustomSynthesizer(BaseSynthesizer):\n def synthesize(\n self,\n query_bundle: QueryBundle,\n nodes: List[NodeWithScore]\n ) -> Response:\n # 自定义合成逻辑\n context_str = \"\\n\\n\".join([n.get_content() for n in nodes])\n # ... 生成响应\n return response\n```\n\n## 查询引擎\n\n### QueryEngine 查询引擎\n\nQueryEngine 是 LlamaIndex 提供的端到端查询接口，整合了检索和响应合成两个环节。查询引擎接收用户查询，自动执行检索流程，并生成最终响应。\n\n```mermaid\ngraph LR\n A[Query 输入] --> B[Retriever 检索]\n B --> C[NodeWithScore 节点列表]\n C --> D[Postprocessor 后处理器]\n D --> E[ResponseSynthesizer 合成器]\n E --> F[Response 输出]\n```\n\n### 查询引擎配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `retriever` | BaseRetriever | 检索器实例 |\n| `response_synthesizer` | Optional[BaseSynthesizer] | 响应合成器 |\n| `node_postprocessors` | List[BaseNodePostprocessor] | 节点后处理器 |\n| `verbose` | bool | 是否输出详细日志 |\n\n### 组合式查询引擎\n\n```python\nfrom llama_index.core import QueryEngine, get_response_synthesizer\n\n# 创建组合式查询引擎\nquery_engine = index.as_query_engine(\n retriever=retriever,\n response_synthesizer=synthesizer,\n node_postprocessors=[\n KeywordNodePostprocessor(similarity_cutoff=0.7),\n SimilarityPostprocessor(threshold=0.8)\n ]\n)\n\n# 执行查询\nresponse = query_engine.query(\"用户问题\")\n```\n\n## 存储与持久化\n\n### StorageContext 存储上下文\n\nStorageContext 管理 LlamaIndex 的数据持久化，提供了统一的存储接口。StorageContext 封装了文档存储、向量存储、图存储等组件。\n\n```mermaid\nclassDiagram\n class StorageContext {\n +docstore: BaseDocumentStore\n +vector_store: BaseVectorStore\n +graph_store: BaseGraphStore\n +index_store: BaseIndexStore\n +from_defaults(): StorageContext\n +persist(): None\n +load(): StorageContext\n }\n \n class BaseDocumentStore {\n <>\n +add_documents(): None\n +get_document(): Document\n +delete_document(): None\n }\n \n class BaseVectorStore {\n <>\n +add(): List[str]\n +delete(): None\n +query(): VectorStoreQueryResult\n }\n \n StorageContext *-- BaseDocumentStore\n StorageContext *-- BaseVectorStore\n StorageContext *-- BaseGraphStore\n```\n\n### 持久化操作\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# 从存储加载索引\nstorage_context = StorageContext.from_defaults(\n persist_dir=\"./storage\"\n)\nindex = load_index_from_storage(storage_context)\n\n# 保存索引\nindex.storage_context.persist(persist_dir=\"./storage\")\n```\n\n## 组件交互流程\n\n### 完整 RAG 流程\n\n以下是 LlamaIndex 核心组件的完整交互流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant QE as QueryEngine\n participant Ret as Retriever\n participant VS as VectorStore\n participant Syn as ResponseSynthesizer\n participant LLM as LLM\n \n User->>QE: query(\"问题\")\n QE->>Ret: retrieve(query_bundle)\n Ret->>VS: similarity_search(embedding)\n VS-->>Ret: List[NodeWithScore]\n Ret-->>QE: List[NodeWithScore]\n QE->>Syn: synthesize(query, nodes)\n Syn->>LLM: generate(prompt)\n LLM-->>Syn: response_text\n Syn-->>QE: Response\n QE-->>User: Response\n```\n\n### 数据流向总结\n\n| 阶段 | 组件 | 数据格式 | 说明 |\n|------|------|---------|------|\n| 文档加载 | DocumentLoader | Document | 从各种来源加载原始文档 |\n| 分块处理 | NodeParser | List[Node] | 将文档分割为语义块 |\n| 向量化 | EmbedModel | List[float] | 计算文本向量表示 |\n| 索引存储 | VectorStore | VectorStoreRecord | 存储向量和元数据 |\n| 检索查询 | Retriever | List[NodeWithScore] | 根据相似度检索 |\n| 响应生成 | ResponseSynthesizer | Response | 生成自然语言回答 |\n\n## 最佳实践\n\n### 组件选择指南\n\n| 需求场景 | 推荐索引类型 | 检索器类型 |\n|---------|-------------|-----------|\n| 语义搜索 | VectorStoreIndex | VectorRetriever |\n| 关系查询 | KnowledgeGraphIndex | KnowledgeGraphRetriever |\n| 复杂关系网络 | PropertyGraphIndex | PropertyGraphRetriever |\n| 高精度问答 | VectorStoreIndex + KnowledgeGraphIndex | EnsembleRetriever |\n\n### 性能优化建议\n\n1. **批量处理**：使用批量 API 进行文档索引和检索\n2. **缓存策略**：启用向量和结果的缓存\n3. **异步操作**：使用 async API 提高并发性能\n4. **索引优化**：合理设置块大小和重叠参数\n\n### 错误处理\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\ntry:\n index = VectorStoreIndex.from_documents(documents)\n query_engine = index.as_query_engine()\n response = query_engine.query(\"问题\")\nexcept Exception as e:\n # 错误处理逻辑\n print(f\"发生错误: {e}\")\n```\n\n## 总结\n\nLlamaIndex 的核心组件体系提供了从文档处理到智能问答的完整技术栈。Document 和 Node 构成了数据模型的基础；VectorStoreIndex、PropertyGraphIndex 和 KnowledgeGraphIndex 提供了多样化的索引能力；Retriever 和 ResponseSynthesizer 则负责检索和响应生成的关键环节。这些组件通过统一的接口设计实现了高度的可组合性和可扩展性，使开发者能够灵活构建满足各种需求的 RAG 应用。\n\n---\n\n\n\n## 数据摄取流程\n\n### 相关页面\n\n相关主题：[节点解析器](#node_parsing), [存储层架构](#storage_layer), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/ingestion/pipeline.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/pipeline.py)\n- [llama-index-core/llama_index/core/readers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/base.py)\n- [llama-index-core/llama_index/core/readers/file/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/file/base.py)\n- [llama-index-core/llama_index/core/ingestion/transformations.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/transformations.py)\n \n\n# 数据摄取流程\n\n## 概述\n\n数据摄取流程（Data Ingestion Pipeline）是LlamaIndex框架中负责从各种数据源加载、转换和处理原始数据的核心模块。该流程将非结构化或半结构化的原始数据转换为标准化的Document对象，供后续的索引构建和检索使用。\n\n数据摄取流程的主要职责包括：\n\n- **数据加载**：从文件、网页、数据库、API等多种来源读取数据\n- **数据解析**：将不同格式的数据（PDF、Word、HTML、Markdown等）解析为文本内容\n- **数据转换**：对文本进行分块、清洗、向量化等预处理操作\n- **流程编排**：通过Pipeline机制协调各个处理环节\n\n```mermaid\ngraph TD\n A[数据源] --> B[Reader读取器]\n B --> C[Document对象]\n C --> D[Transformations转换器]\n D --> E[处理后的Document]\n E --> F[索引构建/存储]\n```\n\n## 核心架构\n\n数据摄取流程由三个主要组件构成：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **Reader** | 从各种来源加载原始数据 | `llama_index/core/readers/` |\n| **Transformation** | 对Document进行转换处理 | `llama_index/core/ingestion/transformations.py` |\n| **IngestionPipeline** | 编排整个摄取流程 | `llama_index/core/ingestion/pipeline.py` |\n\n## 读取器（Readers）\n\n### 读取器基类\n\n所有读取器继承自`BaseReader`基类，定义了统一的数据加载接口：\n\n```python\nfrom llama_index.core.readers.base import BaseReader\n\nclass BaseReader:\n \"\"\"数据读取器基类\"\"\"\n \n def load_data(self, *args, **kwargs) -> List[Document]:\n \"\"\"加载数据并返回Document列表\"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/readers/base.py]()\n\n### 文件读取器\n\n`SimpleDirectoryReader`是文件读取的核心实现，支持从本地目录批量加载文件：\n\n```python\nfrom llama_index.core import SimpleDirectoryReader\n\n# 从目录加载所有支持的文件\nreader = SimpleDirectoryReader(\"./data\")\ndocuments = reader.load_data()\n\n# 指定文件扩展名过滤\nreader = SimpleDirectoryReader(\n \"./data\",\n required_exts=[\".pdf\", \".docx\"]\n)\ndocuments = reader.load_data()\n\n# 递归加载子目录\nreader = SimpleDirectoryReader(\n \"./data\",\n recursive=True\n)\ndocuments = reader.load_data()\n```\n\n资料来源：[llama-index-core/llama_index/core/readers/file/base.py]()\n\n#### SimpleDirectoryReader 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `input_dir` | str | 输入目录路径 |\n| `input_files` | List[Path] | 指定要加载的文件列表 |\n| `recursive` | bool | 是否递归扫描子目录，默认False |\n| `required_exts` | List[str] | 只加载指定扩展名的文件 |\n| `exclude` | List[str] | 排除的文件名模式 |\n| `filename_as_id` | bool | 使用文件名作为Document ID |\n\n### Web读取器\n\nLlamaIndex提供多种网页内容提取器：\n\n| 读取器 | 说明 | 安装包 |\n|--------|------|--------|\n| `TrafilaturaWebReader` | 使用trafilatura提取静态网页文本 | llama-index-readers-web |\n| `UnstructuredURLLoader` | 使用Unstructured.io解析HTML | llama-index-readers-web |\n| `NewsArticleReader` | 解析新闻文章（基于newspaper3k） | llama-index-readers-web |\n| `MainContentExtractorReader` | 提取网页主体内容 | llama-index-readers-web |\n| `ReadabilityWebPageReader` | 使用Readability算法提取正文 | llama-index-readers-web |\n\n```python\nfrom llama_index.readers.web import TrafilaturaWebReader\n\nloader = TrafilaturaWebReader()\ndocuments = loader.load_data(urls=[\"https://example.com/article\"])\n```\n\n### 远程深度读取器\n\n`RemoteDepthReader`支持递归抓取指定深度的链接：\n\n```python\nfrom llama_index.readers.remote_depth import RemoteDepthReader\n\nloader = RemoteDepthReader()\n# depth=2表示提取页面链接 + 链接指向页面的链接\ndocuments = loader.load_data(\n url=\"https://example.com/\",\n depth=2\n)\n```\n\n### 文档解析读取器\n\n| 读取器 | 支持格式 | 安装包 |\n|--------|----------|--------|\n| `DoclingReader` | PDF, DOCX, HTML, JSON | llama-index-readers-docling |\n| `WikipediaReader` | Wikipedia页面 | llama-index-readers-wikipedia |\n| `WordpressReader` | WordPress博客 | llama-index-readers-wordpress |\n| `BagelReader` | Bagel向量数据库 | llama-index-readers-bagel |\n\n## 数据转换（Transformations）\n\n转换器是数据摄取流程中的关键环节，用于对Document进行分块、向量化等处理。\n\n### 转换器类型\n\n| 转换器 | 功能 | 源码位置 |\n|--------|------|----------|\n| `SentenceSplitter` | 按句子/字符数分块 | transformations.py |\n| `TokenTextSplitter` | 按Token数分块 | transformations.py |\n| `RecursiveCharacterTextSplitter` | 递归字符分块 | transformations.py |\n\n### 核心转换器详解\n\n#### SentenceSplitter\n\n按句子边界进行文本分块：\n\n```python\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\n\nsplitter = SentenceSplitter(\n chunk_size=1024, # 块大小（字符数）\n chunk_overlap=20, # 块间重叠字符数\n separator=\" \" # 分隔符\n)\n\nchunked_docs = splitter(documents)\n```\n\n#### TokenTextSplitter\n\n基于Token数量进行智能分块：\n\n```python\nfrom llama_index.core.ingestion.transformations import TokenTextSplitter\n\nsplitter = TokenTextSplitter(\n chunk_size=512, # 块大小（Token数）\n chunk_overlap=50, # 块间重叠Token数\n separator=[\"\\n\\n\", \"\\n\", \" \"] # 分隔优先级\n)\n\nchunked_docs = splitter(documents)\n```\n\n### 转换器参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | int | 1024 | 单个块的目标大小 |\n| `chunk_overlap` | int | 200 | 块间重叠大小 |\n| `separator` | str/List[str] | \"\\n\\n\" | 分隔符 |\n| `backup_separators` | List[str] | None | 备用分隔符列表 |\n\n## 摄取管道（IngestionPipeline）\n\n`IngestionPipeline`是数据摄取流程的核心编排器，协调读取器、转换器和存储后端的工作。\n\n### 基本用法\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\nfrom llama_index.core import VectorStoreIndex\n\n# 创建管道，指定转换器\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=1024, chunk_overlap=20)\n ]\n)\n\n# 对文档执行管道\nprocessed_docs = pipeline.run(documents=raw_documents)\n\n# 创建索引\nindex = VectorStoreIndex.from_documents(processed_docs)\n```\n\n### 完整摄取流程图\n\n```mermaid\ngraph LR\n A[原始文档] --> B[管道处理]\n B --> C{是否配置存储?}\n C -->|是| D[存储到向量数据库]\n C -->|否| E[返回Document列表]\n D --> F[构建索引]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n```\n\n### 管道缓存\n\nIngestionPipeline支持缓存机制以提升重复执行效率：\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\n\npipeline = IngestionPipeline(\n transformations=[...],\n docstore=SimpleDocumentStore() # 启用文档缓存\n)\n\n# 首次运行会处理所有文档\ndocs1 = pipeline.run(documents=documents)\n\n# 再次运行时，已缓存的文档会被跳过\ndocs2 = pipeline.run(documents=documents)\n```\n\n## 数据摄取完整流程\n\n```mermaid\nflowchart TD\n subgraph 数据源\n A1[本地文件]\n A2[网页内容]\n A3[数据库]\n A4[API接口]\n end\n \n subgraph 读取层\n B1[FileReader]\n B2[WebReader]\n B3[APILoader]\n end\n \n subgraph 转换层\n C1[文本分块]\n C2[元数据提取]\n C3[向量化]\n end\n \n subgraph 输出层\n D1[Document对象]\n D2[向量索引]\n D3[知识图谱]\n end\n \n A1 --> B1\n A2 --> B2\n A3 --> B3\n A4 --> B3\n \n B1 --> C1\n B2 --> C1\n B3 --> C1\n \n C1 --> C2\n C2 --> C3\n \n C3 --> D1\n C3 --> D2\n C3 --> D3\n```\n\n## 使用示例\n\n### 完整文件摄取示例\n\n```python\nfrom llama_index.core import SimpleDirectoryReader, VectorStoreIndex\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\n\n# 1. 加载文档\nreader = SimpleDirectoryReader(\"./data\", recursive=True)\ndocuments = reader.load_data()\n\n# 2. 创建摄取管道\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=1024, chunk_overlap=128)\n ]\n)\n\n# 3. 处理文档\nprocessed_docs = pipeline.run(documents=documents)\n\n# 4. 构建索引\nindex = VectorStoreIndex.from_documents(processed_docs)\n\n# 5. 查询\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"相关问题\")\n```\n\n### 带向量化嵌入的摄取\n\n```python\nfrom llama_index.core.ingestion import IngestionPipeline\nfrom llama_index.core.ingestion.transformations import SentenceSplitter\nfrom llama_index.embeddings.ollama import OllamaEmbedding\n\n# 配置嵌入模型\nembed_model = OllamaEmbedding(\n model_name=\"nomic-embed-text\",\n base_url=\"http://localhost:11434\"\n)\n\n# 创建包含嵌入的管道\npipeline = IngestionPipeline(\n transformations=[\n SentenceSplitter(chunk_size=512),\n embed_model # 添加嵌入转换\n ]\n)\n\ndocs = pipeline.run(documents=raw_docs)\n```\n\n## 最佳实践\n\n### 1. 合理设置分块大小\n\n| 使用场景 | 推荐chunk_size | 说明 |\n|----------|----------------|------|\n| 问答系统 | 512-1024 | 适合精确答案检索 |\n| 摘要生成 | 2048-4096 | 需要更多上下文 |\n| 语义搜索 | 256-512 | 更细粒度的匹配 |\n\n### 2. 块重叠设置\n\n```python\n# 较大重叠适用于：\n# - 跨块边界的问答\n# - 需要保留上下文连贯性\n# - 文档结构不规则\n\nsplitter = SentenceSplitter(\n chunk_size=1024,\n chunk_overlap=256 # 25%重叠\n)\n```\n\n### 3. 选择合适的读取器\n\n| 数据源 | 推荐读取器 | 理由 |\n|--------|-----------|------|\n| 本地文件（多格式） | SimpleDirectoryReader | 统一接口，支持多种格式 |\n| 新闻文章 | NewsArticleReader | 专门优化新闻格式 |\n| 静态网站 | TrafilaturaWebReader | 高质量文本提取 |\n| PDF文档 | DoclingReader | 保留布局和结构 |\n\n## 相关资源\n\n- [IngestionPipeline官方文档](https://docs.llamaindex.ai/en/stable/api_reference/ingestion/)\n- [Reader集成列表](https://llamahub.ai/)\n- [Ollama嵌入模型配置](./llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)\n\n---\n\n\n\n## 节点解析器\n\n### 相关页面\n\n相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/node_parser/text/sentence.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/sentence.py)\n- [llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py)\n- [llama-index-core/llama_index/core/node_parser/relational/markdown_element.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/relational/markdown_element.py)\n- [llama-index-core/llama_index/core/node_parser/interface.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/interface.py)\n- [llama-index-core/llama_index/core/node_parser/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/__init__.py)\n \n\n# 节点解析器\n\n## 概述\n\n节点解析器（Node Parser）是 LlamaIndex 框架中负责将文档（Document）拆分为结构化节点（Node）序列的核心组件。在检索增强生成（RAG）工作流中，节点解析器扮演着至关重要的角色，它决定了如何将原始文本分割成适合检索和上下文处理的最小单元。\n\n节点解析器的主要职责包括：\n\n- **文本分割**：将长文档按照指定规则拆分为较小的文本块\n- **结构保留**：在分割过程中维护文档的层次结构和语义完整性\n- **元数据提取**：为每个节点附加相关的上下文信息和元数据\n- **关系建立**：建立节点之间的关系，支持后续的图结构查询\n\n资料来源：[interface.py:1-50]()\n\n## 核心接口\n\n### NodeParser 基类\n\n所有节点解析器都继承自 `NodeParser` 接口，该接口定义了节点解析的核心抽象方法。\n\n```mermaid\nclassDiagram\n class NodeParser {\n <>\n +get_nodes() List[Node]\n +get_nodes_from_documents() List[Node]\n }\n \n class BaseNodeParser {\n <>\n +get_nodes() List[Node]\n +get_nodes_from_documents() List[Node]\n }\n \n class SentenceSplitter {\n +sentence_separator: str\n +chunk_size: int\n +chunk_overlap: int\n }\n \n class SemanticSplitter {\n +embed_model: BaseEmbedding\n +buffer_size: int\n +embed_batch_size: int\n }\n \n class MarkdownElementNodeParser {\n +use_json: bool\n +merge_many_element: bool\n }\n \n NodeParser <|.. BaseNodeParser\n BaseNodeParser <|-- SentenceSplitter\n BaseNodeParser <|-- SemanticSplitter\n BaseNodeParser <|-- MarkdownElementNodeParser\n```\n\n### 核心方法\n\n| 方法名 | 参数 | 返回类型 | 说明 |\n|--------|------|----------|------|\n| `get_nodes` | documents: List[Document] | List[BaseNode] | 将文档列表转换为节点列表 |\n| `get_nodes_from_documents` | documents: List[Document], show_progress: bool | List[BaseNode] | 带进度显示的文档转换方法 |\n\n资料来源：[interface.py:50-120]()\n\n## 文本节点解析器\n\n### SentenceSplitter（句子分割器）\n\n`SentenceSplitter` 是最基本的节点解析器，它按照句子边界和字符数限制对文本进行分割。\n\n#### 主要配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | int | 1024 | 每个文本块的字符数上限 |\n| `chunk_overlap` | int | 200 | 相邻文本块之间的重叠字符数 |\n| `sentence_separator` | str | \"\\n\\n\" | 句子分隔符 |\n| `paragraph_separator` | str | \"\\n\\n\\n\" | 段落分隔符 |\n| `secondary_chunking_regex` | Optional[Pattern] | None | 次级分割正则表达式 |\n| `coalesce_chunk_size` | Optional[int] | None | 合并后的目标块大小 |\n\n#### 工作原理\n\n```mermaid\nflowchart TD\n A[输入文档] --> B[按段落分割]\n B --> C[计算段落长度]\n C --> D{段落长度 > chunk_size?}\n D -->|是| E[按句子分割段落]\n D -->|否| F[直接添加到当前块]\n E --> G{句子长度 > chunk_size?}\n G -->|是| H[按次级正则表达式分割]\n G -->|否| I[添加到当前块]\n H --> J[按chunk_size限制]\n I --> K{当前块已满?}\n J --> K\n F --> K\n K -->|是| L[创建新块]\n K -->|否| M[继续添加]\n L --> N[应用chunk_overlap]\n M --> N\n N --> O[输出节点列表]\n```\n\n资料来源：[sentence.py:1-150]()\n\n### SemanticSplitter（语义分割器）\n\n`SemanticSplitter` 是一种更高级的分割策略，它利用嵌入模型（Embedding Model）来识别语义边界，从而产生更加连贯的文本块。\n\n#### 核心概念\n\n**缓冲区机制**：SemanticSplitter 使用固定大小的缓冲区来聚合相邻句子，然后通过计算相邻缓冲区之间的语义相似度来决定分割点。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `embed_model` | BaseEmbedding | 必需 | 用于计算语义的嵌入模型 |\n| `buffer_size` | int | 1 | 相邻句子缓冲大小 |\n| `breakpoint_percent_threshold` | float | 0.5 | 触发分割的差异百分比阈值 |\n| `embed_batch_size` | int | 100 | 嵌入计算批量大小 |\n\n#### 分割策略\n\n```mermaid\nflowchart LR\n A[句子序列] --> B[缓冲区聚合]\n B --> C[计算相邻缓冲区嵌入]\n C --> D[计算余弦相似度]\n D --> E{相似度差异 > 阈值?}\n E -->|是| F[插入分割点]\n E -->|否| G[继续聚合]\n F --> H[生成语义节点]\n G --> B\n```\n\n语义分割器特别适合处理需要保持语义完整性的场景，例如问答系统、文档摘要等应用。\n\n资料来源：[semantic_splitter.py:1-200]()\n\n## Markdown 元素解析器\n\n### MarkdownElementNodeParser\n\n`MarkdownElementNodeParser` 专门用于解析 Markdown 格式的文档，它能够识别 Markdown 中的各种元素类型并分别处理。\n\n#### 支持的元素类型\n\n| 元素类型 | 说明 | 处理方式 |\n|----------|------|----------|\n| `TitleElement` | 标题元素 | 作为独立节点或用于分组 |\n| `CodeElement` | 代码块 | 保持格式，包含语言标识 |\n| `TableElement` | 表格元素 | 解析为结构化数据 |\n| `NarrativeTextElement` | 叙述文本 | 标准文本块处理 |\n| `QuestionAnswerElement` | 问答对 | 结构化问答提取 |\n\n#### 配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `use_json` | bool | False | 是否输出 JSON 格式 |\n| `include_metadata` | bool | True | 是否包含元数据 |\n| `include_prev_next_rel` | bool | True | 是否添加前后关系 |\n| `merge_many_element` | bool | True | 是否合并连续同类型元素 |\n\n#### 输出结构\n\n```mermaid\ngraph TD\n A[Markdown文档] --> B[解析标题层级]\n A --> C[提取代码块]\n A --> D[识别表格]\n A --> E[处理段落文本]\n B --> F[创建TitleElement节点]\n C --> G[创建CodeElement节点]\n D --> H[创建TableElement节点]\n E --> I[创建NarrativeTextElement节点]\n F --> J[建立标题-内容关系]\n G --> J\n H --> J\n I --> J\n J --> K[输出节点图结构]\n```\n\n当 `use_json=True` 时，解析器会输出符合 Docling 规范的 JSON 格式，需要配合 Docling Node Parser 使用。\n\n资料来源：[markdown_element.py:1-250]()\n\n## 使用指南\n\n### 基本使用示例\n\n#### 简单句子分割\n\n```python\nfrom llama_index.core.node_parser import SentenceSplitter\n\n# 初始化分割器\nnode_parser = SentenceSplitter(\n chunk_size=512,\n chunk_overlap=50\n)\n\n# 从文档获取节点\nnodes = node_parser.get_nodes_from_documents(documents)\n```\n\n#### 语义分割\n\n```python\nfrom llama_index.core.node_parser import SemanticSplitter\nfrom llama_index.core.embeddings import OpenAIEmbedding\n\n# 初始化嵌入模型\nembed_model = OpenAIEmbedding()\n\n# 创建语义分割器\nsemantic_splitter = SemanticSplitter(\n embed_model=embed_model,\n buffer_size=1,\n breakpoint_percent_threshold=0.5\n)\n\nnodes = semantic_splitter.get_nodes_from_documents(documents)\n```\n\n#### Markdown 解析\n\n```python\nfrom llama_index.core.node_parser import MarkdownElementNodeParser\n\nparser = MarkdownElementNodeParser(\n use_json=False,\n merge_many_element=True\n)\n\nnodes = parser.get_nodes_from_documents(markdown_documents)\n```\n\n### 高级配置\n\n```python\nfrom llama_index.core.node_parser import SentenceSplitter\n\n# 精细化配置\nsplitter = SentenceSplitter(\n chunk_size=1024,\n chunk_overlap=200,\n sentence_separator=\"。\", # 中文句号\n paragraph_separator=\"\\n\\n\",\n secondary_chunking_regex=\"[^，,]+[,，]?\", # 按逗号次级分割\n coalesce_chunk_size=None # 禁用合并\n)\n```\n\n## 架构设计\n\n### 节点类型层次结构\n\n```mermaid\nclassDiagram\n class BaseNode {\n <>\n +id_: str\n +embedding: Optional[List[float]]\n +metadata: Dict\n +relationships: Dict\n }\n \n class TextNode {\n +text: str\n +start_char_idx: int\n +end_char_idx: int\n }\n \n class IndexNode {\n +index_id: str\n +node_id: str\n }\n \n class DocumentRelationship {\n +SOURCE, PREVIOUS, NEXT, PARENT, CHILD\n }\n \n BaseNode <|-- TextNode\n BaseNode <|-- IndexNode\n```\n\n### 数据流\n\n```mermaid\nflowchart TD\n subgraph 输入层\n A1[Document对象]\n A2[文本内容]\n A3[元数据字典]\n end\n \n subgraph 解析层\n B1[节点解析器选择]\n B2[文本分割逻辑]\n B3[边界检测]\n end\n \n subgraph 处理层\n C1[节点创建]\n C2[关系建立]\n C3[元数据附加]\n end\n \n subgraph 输出层\n D1[BaseNode列表]\n D2[节点关系图]\n end\n \n A1 --> B1\n A2 --> B2\n A3 --> B3\n B1 --> C1\n B2 --> C2\n B3 --> C3\n C1 --> D1\n C2 --> D2\n```\n\n## 最佳实践\n\n### 分割策略选择指南\n\n| 应用场景 | 推荐解析器 | 理由 |\n|----------|-----------|------|\n| 通用文档处理 | SentenceSplitter | 简单高效，开销小 |\n| 语义连贯性要求高 | SemanticSplitter | 保持语义完整性 |\n| Markdown 文档 | MarkdownElementNodeParser | 保留文档结构 |\n| 代码文档 | MarkdownElementNodeParser | 保护代码块 |\n| 结构化数据 | MarkdownElementNodeParser | 解析表格和列表 |\n\n### 参数调优建议\n\n**chunk_size 设置**：\n\n- 小块（256-512）：适合精确检索，高细粒度\n- 中块（512-1024）：平衡检索精度和上下文完整性\n- 大块（1024-2048）：适合需要完整语境的查询\n\n**chunk_overlap 设置**：\n\n- 通常设置为 chunk_size 的 10%-20%\n- 过高会增加冗余和处理时间\n- 适用于边界信息重要的场景\n\n## 相关模块\n\n节点解析器与其他 LlamaIndex 核心组件协同工作：\n\n- **Document**：原始文档输入\n- **VectorStoreIndex**：节点用于向量索引构建\n- **BaseEmbedding**：语义分割依赖的嵌入模型\n- **Retriever**：基于节点进行信息检索\n\n## 总结\n\n节点解析器是 LlamaIndex 数据处理管道中的关键环节，它通过多种策略将非结构化文档转换为结构化的节点序列。框架提供了从简单到复杂的多种解析器实现，开发者可以根据具体需求选择合适的工具。正确配置节点解析器对于构建高效的 RAG 系统至关重要。\n\n资料来源：[__init__.py:1-50]()\n\n---\n\n\n\n## 存储层架构\n\n### 相关页面\n\n相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)\n- [llama-index-core/llama_index/core/vector_stores/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/vector_stores/types.py)\n- [llama-index-core/llama_index/core/storage/docstore/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/types.py)\n- [llama-index-core/llama_index/core/storage/chat_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/chat_store/base.py)\n \n\n# 存储层架构\n\n## 概述\n\nLlamaIndex 的存储层架构是一套完整的数据持久化解决方案，负责管理向量数据、文档数据、聊天记录等核心数据的存储与检索。该架构采用模块化设计，通过抽象接口支持多种存储后端，使开发者能够灵活选择适合自身场景的存储方案。\n\n存储层主要由三个核心组件构成：**VectorStore**（向量存储）、**Docstore**（文档存储）和 **ChatStore**（聊天存储）。这些组件通过统一的 **StorageContext**（存储上下文）进行协调管理，实现了数据访问与存储实现的解耦。\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[StorageContext] --> B[VectorStore]\n A --> C[Docstore]\n A --> C1[IndexStore]\n A --> D[ChatStore]\n A --> E[ImageStore]\n \n B --> B1[SimpleVectorStore]\n B --> B2[FaissVectorStore]\n B --> B3[MilvusVectorStore]\n B --> B4[PineconeVectorStore]\n \n C --> C2[SimpleDocstore]\n C --> C3[MongoDocstore]\n C --> C4[DynamoDBDocstore]\n \n D --> D1[SimpleChatStore]\n D --> D2[RedisChatStore]\n```\n\n### 存储上下文（StorageContext）\n\nStorageContext 是 LlamaIndex 存储层的中央协调器，负责初始化和管理所有存储组件的实例。它提供了统一的接口来访问向量存储、文档存储、索引存储和聊天存储。\n\n**主要属性：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `vector_store` | VectorStore | 向量存储实例 |\n| `docstore` | BaseDocstore | 文档存储实例 |\n| `index_store` | IndexStore | 索引存储实例 |\n| `chat_store` | ChatStore | 聊天存储实例 |\n| `image_store` | ImageStore | 图片存储实例 |\n\n**持久化方法：**\n\n```python\n# 持久化到磁盘\nindex.storage_context.persist(persist_dir=\"./storage\")\n\n# 从磁盘加载\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\nindex = load_index_from_storage(storage_context)\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py]()\n\n## 向量存储层（VectorStore）\n\n### 向量存储类型定义\n\n向量存储层负责存储和检索高维向量嵌入，是 RAG（检索增强生成）系统的核心组件。\n\n```mermaid\nclassDiagram\n class VectorStore {\n <>\n +add() List[str]\n +delete() None\n +query() List[Node]\n +get_nodes() List[BaseNode]\n +get_metadata_dict() Dict\n +delete_ref_doc() None\n +persist() None\n }\n \n class BasePydanticVectorStore {\n <>\n +client: Any\n }\n \n class VectorStoreQuery {\n <>\n +query_embedding: Optional[List[float]]\n +similarity_top_k: int\n +mode: VectorStoreQueryMode\n +filters: Optional[MetadataFilters]\n }\n \n VectorStore <|-- BasePydanticVectorStore\n```\n\n### 查询模式\n\n| 模式 | 说明 |\n|------|------|\n| `DEFAULT` | 默认相似度搜索 |\n| `MMR` | 最大边际相关性（Maximal Marginal Relevance） |\n| `HYBRID` | 混合搜索（向量+关键词） |\n\n### 查询参数结构\n\n```python\n@dataclass\nclass VectorStoreQuery:\n query_embedding: Optional[List[float]] = None\n query_str: Optional[str] = None\n similarity_top_k: int = 4\n docs: Optional[List[Document]] = None\n alpha: float = 0.5 # 用于混合搜索的权重\n nn: Optional[NearestNeighborsAlgo] = None\n mode: VectorStoreQueryMode = VectorStoreQueryMode.DEFAULT\n filters: Optional[MetadataFilters] = None\n MMR: bool = False\n mmr_threshold: Optional[float] = None\n```\n\n资料来源：[llama-index-core/llama_index/core/vector_stores/types.py]()\n\n## 文档存储层（Docstore）\n\n### 文档存储接口\n\n文档存储层负责存储原始文档及其元数据，为索引构建和检索提供文档基础。\n\n```mermaid\ngraph LR\n A[Document] --> B[BaseDocstore]\n B --> C1[SimpleDocstore]\n B --> C2[MongoDocstore]\n B --> C3[DynamoDBDocstore]\n B --> C4[ElasticsearchDocstore]\n```\n\n### 文档存储类型\n\n| 类型 | 后端 | 适用场景 |\n|------|------|----------|\n| SimpleDocstore | 内存/本地文件 | 开发测试、小规模数据 |\n| MongoDocstore | MongoDB | 分布式部署、大规模数据 |\n| DynamoDBDocstore | AWS DynamoDB | 云原生应用、高可用需求 |\n| ElasticsearchDocstore | Elasticsearch | 全文搜索场景 |\n\n### 文档数据结构\n\n```python\n@dataclass\nclass Document:\n id_: str\n embedding: Optional[List[float]] = None\n metadata: Dict[str, Any] = field(default_factory=dict)\n excluded_embed_metadata_keys: List[str] = field(default_factory=list)\n excluded_llm_metadata_keys: List[str] = field(default_factory=list)\n relationships: Dict[DocumentRelationship, List[str]] = field(default_factory=dict)\n hash: Optional[str] = None\n text: str = \"\"\n start_char_idx: Optional[int] = None\n end_char_idx: Optional[int] = None\n text_template: str = \"{metadata_str}\\n\\n{content}\"\n metadata_template: str = \"{key}: {value}\"\n metadata_separator: str = \"\\n\"\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/docstore/types.py]()\n\n## 聊天存储层（ChatStore）\n\n### 聊天存储架构\n\n聊天存储层用于持久化管理对话历史，支持多轮对话场景和上下文管理。\n\n```mermaid\ngraph TD\n A[ChatMessage] --> B[BaseChatStore]\n B --> C1[SimpleChatStore]\n B --> C2[RedisChatStore]\n B --> C3[MongoChatStore]\n \n D[ChatStoreConfig] --> B\n E[ChatSession] --> D\n```\n\n### 聊天消息类型\n\n| 类型 | 说明 |\n|------|------|\n| `ChatMessageRole.AI` | AI 助手消息 |\n| `ChatMessageRole.USER` | 用户消息 |\n| `ChatMessageRole.SYSTEM` | 系统消息 |\n| `ChatMessageRole.TOOL` | 工具消息 |\n\n### 聊天存储接口\n\n```python\nclass BaseChatStore(ABC):\n @abstractmethod\n def add_message(self, key: str, message: ChatMessage) -> None:\n pass\n \n @abstractmethod\n def get_messages(self, key: str) -> List[ChatMessage]:\n pass\n \n @abstractmethod\n def delete_messages(self, key: str) -> None:\n pass\n \n @abstractmethod\n def delete_message(self, key: str, idx: int) -> None:\n pass\n \n @abstractmethod\n def delete_all_messages(self, key: str) -> None:\n pass\n \n @abstractmethod\n def get_latest_message(self, key: str) -> Optional[ChatMessage]:\n pass\n \n @abstractmethod\n def as_langchain_chat_history(self, **kwargs: Any) -> BaseChatMessageHistory:\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/chat_store/base.py]()\n\n## 数据流与工作流程\n\n### 索引构建流程\n\n```mermaid\ngraph TD\n A[加载文档] --> B[文本分块]\n B --> C[生成嵌入向量]\n C --> D[存储到Docstore]\n C --> E[存储到VectorStore]\n D --> F[构建索引结构]\n E --> F\n F --> G[持久化存储]\n```\n\n### 检索查询流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询向量化]\n B --> C[向量相似度搜索]\n C --> D{混合搜索?}\n D -->|是| E[关键词搜索]\n D -->|否| F[获取Top-K结果]\n E --> F\n F --> G[结果重排序]\n G --> H[返回上下文]\n```\n\n## 存储配置选项\n\n### StorageContext 构造参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vector_store` | VectorStore | SimpleVectorStore | 向量存储实例 |\n| `docstore` | BaseDocstore | SimpleDocumentStore | 文档存储实例 |\n| `index_store` | IndexStore | SimpleIndexStore | 索引存储实例 |\n| `chat_store` | ChatStore | None | 聊天存储实例 |\n| `persist_dir` | str | None | 持久化目录路径 |\n| `graph_store` | GraphStore | None | 知识图谱存储 |\n\n### 持久化配置\n\n```python\n# 完整配置示例\nstorage_context = StorageContext.from_defaults(\n vector_store=vector_store,\n docstore=docstore,\n index_store=index_store,\n persist_dir=\"./storage\"\n)\n\n# 手动持久化\nstorage_context.persist(persist_dir=\"./storage\")\n\n# 从持久化目录加载\nstorage_context = StorageContext.from_defaults(\n persist_dir=\"./storage\"\n)\n```\n\n## 存储后端兼容性\n\n### 向量存储后端矩阵\n\n| 后端 | 支持元数据过滤 | 支持混合搜索 | 支持删除 | 支持更新 |\n|------|---------------|-------------|---------|---------|\n| SimpleVectorStore | ✅ | ❌ | ✅ | ❌ |\n| Faiss | ✅ | ❌ | ❌ | ❌ |\n| Pinecone | ✅ | ✅ | ✅ | ✅ |\n| Weaviate | ✅ | ✅ | ✅ | ✅ |\n| Milvus | ✅ | ✅ | ✅ | ✅ |\n| Chroma | ✅ | ❌ | ✅ | ❌ |\n\n## 最佳实践\n\n### 生产环境存储配置\n\n1. **向量存储选择**：对于大规模向量检索场景，推荐使用专门的向量数据库如 Milvus、Pinecone 或 Weaviate\n2. **文档存储选择**：需要支持事务和分布式部署时，选择 MongoDB 或 DynamoDB\n3. **数据持久化**：生产环境务必配置持久化，定期备份存储目录\n\n### 性能优化建议\n\n| 场景 | 优化策略 |\n|------|----------|\n| 大规模向量检索 | 使用支持索引的向量数据库，调整 `similarity_top_k` 参数 |\n| 高频写入 | 批量写入，使用异步持久化 |\n| 内存限制 | 使用磁盘持久化的存储后端，及时释放缓存 |\n| 多模态数据 | 分离图片存储和文本存储，独立管理 |\n\n## 总结\n\nLlamaIndex 的存储层架构通过抽象化的接口设计，实现了存储逻辑与业务逻辑的解耦。开发者可以根据实际需求选择合适的存储后端，无需修改上层代码即可切换存储方案。StorageContext 作为统一的入口，提供了简洁的配置接口和持久化机制，确保了数据的安全性和可移植性。\n\n---\n\n\n\n## 智能体系统\n\n### 相关页面\n\n相关主题：[工作流引擎](#workflow_engine), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/agent/react/formatter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/react/formatter.py)\n- [llama-index-core/llama_index/core/agent/workflow/base_agent.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/base_agent.py)\n- [llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py)\n- [llama-index-core/llama_index/core/tools/function_tool.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/tools/function_tool.py)\n \n\n# 智能体系统\n\n## 概述\n\nLlamaIndex 的智能体系统（Agent System）是一个用于构建、编排和管理基于大型语言模型（LLM）的智能体的核心框架。该系统提供了灵活的架构，支持单智能体和多智能体工作流，使开发者能够创建能够执行复杂任务、调用外部工具、处理多轮对话的 AI 应用。\n\n智能体系统的核心设计理念是将 LLM 与外部工具、数据源和执行环境解耦，通过标准化的接口实现智能体的感知、推理和行动能力。\n\n## 核心架构\n\n### 系统组件关系图\n\n```mermaid\ngraph TD\n User[用户] --> Agent[智能体]\n Agent --> Tool[工具集]\n Agent --> LLM[大语言模型]\n Agent --> Memory[记忆模块]\n Tool --> ExternalAPI[外部 API]\n Tool --> Function[函数调用]\n Tool --> DataSource[数据源]\n Memory --> Context[上下文存储]\n```\n\n### 核心模块\n\n| 模块名称 | 功能描述 | 主要类 |\n|---------|---------|--------|\n| Agent Core | 智能体核心引擎 | `BaseAgent`, `ReActAgent` |\n| Workflow | 工作流编排 | `MultiAgentWorkflow` |\n| Tools | 工具管理 | `FunctionTool`, `QueryTool` |\n| Memory | 记忆管理 | `ChatMemory`, `ContextMemory` |\n| Formatter | 输出格式化 | `ReActFormatter` |\n\n## ReAct 智能体\n\n### 工作原理\n\nReAct（Reasoning + Acting）智能体是 LlamaIndex 实现的核心智能体类型之一，它通过交替执行推理（Reasoning）和行动（Acting）步骤来解决问题。\n\n```mermaid\ngraph LR\n A[用户输入] --> B[LLM 推理]\n B --> C[生成行动]\n C --> D[执行工具]\n D --> E[观察结果]\n E --> B\n B --> F{是否完成}\n F -->|是| G[返回结果]\n F -->|否| B\n```\n\n### ReActFormatter\n\n`ReActFormatter` 负责为 ReAct 智能体生成格式化的提示词模板，它定义了智能体在推理过程中的思考框架和行动规范。\n\n主要功能包括：\n\n- 生成系统提示词模板\n- 定义思考（Thought）、行动（Action）、观察（Observation）的格式规范\n- 管理工具调用的上下文信息\n\n**文件位置：** `llama-index-core/llama_index/core/agent/react/formatter.py`\n\n## 工作流系统\n\n### BaseAgent 基础类\n\n`BaseAgent` 是所有智能体的基类，定义了智能体的核心接口和行为规范。\n\n| 方法 | 功能描述 |\n|-----|---------|\n| `chat()` | 处理单轮对话 |\n| `chat_with_sources()` | 返回带来源的对话结果 |\n| `reset()` | 重置智能体状态 |\n| `stream_chat()` | 流式对话处理 |\n\n### 多智能体工作流\n\n`MultiAgentWorkflow` 实现了多智能体协作框架，允许定义多个专业化的智能体并协调它们之间的交互。\n\n```mermaid\ngraph TD\n A[用户请求] --> B[调度器]\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```\n\n**文件位置：** `llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py`\n\n## 工具系统\n\n### FunctionTool\n\n`FunctionTool` 是 LlamaIndex 中用于封装可调用函数的工具类，它将 Python 函数转换为智能体可以调用的工具。\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\n# 定义一个函数\ndef search_database(query: str) -> str:\n \"\"\"在数据库中搜索相关信息\"\"\"\n # 实现搜索逻辑\n return f\"找到关于 {query} 的结果\"\n\n# 转换为工具\nsearch_tool = FunctionTool.from_defaults(\n fn=search_database,\n name=\"database_search\",\n description=\"用于搜索数据库中的信息\"\n)\n```\n\n### 工具特性\n\n| 特性 | 说明 |\n|-----|-----|\n| 函数包装 | 将 Python 函数转换为可被智能体调用的工具 |\n| 元数据管理 | 支持 name、description 等元数据定义 |\n| 参数验证 | 自动验证输入参数类型和格式 |\n| 结果序列化 | 处理函数返回值以供 LLM 理解 |\n\n**文件位置：** `llama-index-core/llama_index/core/tools/function_tool.py`\n\n## 智能体执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as 智能体\n participant L as LLM\n participant T as 工具\n participant M as 记忆\n\n U->>A: 发送请求\n A->>M: 获取上下文\n A->>L: 生成推理\n L-->>A: 返回思考结果\n A->>T: 调用工具\n T-->>A: 返回观察结果\n A->>L: 基于观察继续推理\n L-->>A: 返回最终决策\n A->>M: 更新记忆\n A-->>U: 返回响应\n```\n\n## 使用示例\n\n### 创建基础智能体\n\n```python\nfrom llama_index.core.agent import ReActAgent\nfrom llama_index.core.tools import FunctionTool\nfrom llama_index.llms.openai import OpenAI\n\n# 初始化 LLM\nllm = OpenAI(model=\"gpt-4\")\n\n# 创建工具\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 今天是晴天，25°C\"\n\nweather_tool = FunctionTool.from_defaults(\n fn=get_weather,\n name=\"get_weather\",\n description=\"获取特定位置的天气信息\"\n)\n\n# 创建智能体\nagent = ReActAgent.from_tools(\n tools=[weather_tool],\n llm=llm,\n verbose=True\n)\n\n# 对话\nresponse = agent.chat(\"北京的天气怎么样？\")\nprint(response)\n```\n\n### 多智能体协作\n\n```python\nfrom llama_index.core.agent.workflow import MultiAgentWorkflow\n\n# 创建多个专业智能体\nresearch_agent = ReActAgent.from_tools(...)\nanalysis_agent = ReActAgent.from_tools(...)\n\n# 创建工作流\nworkflow = MultiAgentWorkflow(agents=[\n research_agent,\n analysis_agent\n])\n\n# 执行工作流\nresult = workflow.run(task=\"分析市场趋势\")\n```\n\n## 配置选项\n\n### 智能体配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `max_iterations` | int | 10 | 最大迭代次数 |\n| `timeout` | float | 60.0 | 单次工具调用超时时间（秒） |\n| `verbose` | bool | False | 是否输出详细日志 |\n| `tool_choice` | str | \"auto\" | 工具选择策略 |\n\n### 工具配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `name` | str | 必填 | 工具名称 |\n| `description` | str | 必填 | 工具描述（LLM 使用） |\n| `fn_schema` | BaseModel | None | 函数参数模式 |\n| `return_direct` | bool | False | 是否直接返回结果 |\n\n## 最佳实践\n\n### 1. 工具设计原则\n\n- 为每个工具提供清晰、具体的描述\n- 使用类型提示定义参数模式\n- 保持工具职责单一性\n- 处理异常情况并返回有意义的错误信息\n\n### 2. 智能体配置建议\n\n- 根据任务复杂度调整 `max_iterations`\n- 设置合理的超时时间\n- 使用 `verbose=True` 进行调试\n- 合理管理智能体的记忆和上下文\n\n### 3. 性能优化\n\n- 批量处理独立的工具调用\n- 使用缓存减少重复计算\n- 限制上下文长度以控制成本\n- 选择合适的 LLM 模型\n\n## 扩展开发\n\n### 自定义智能体类型\n\n```python\nfrom llama_index.core.agent import BaseAgent\n\nclass CustomAgent(BaseAgent):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n \n def chat(self, message: str) -> Response:\n # 实现自定义对话逻辑\n pass\n \n def reset(self) -> None:\n # 实现重置逻辑\n pass\n```\n\n### 自定义工具类型\n\n```python\nfrom llama_index.core.tools import BaseTool\n\nclass CustomTool(BaseTool):\n @property\n def name(self) -> str:\n return \"custom_tool\"\n \n @property\n def description(self) -> str:\n return \"自定义工具描述\"\n \n def _call(self, *args, **kwargs) -> str:\n # 实现工具逻辑\n pass\n```\n\n## 相关资源\n\n- 官方文档：[LlamaIndex Agent Documentation](https://docs.llamaindex.ai/en/stable/module_guides/agents/)\n- 示例代码：[Agent Examples](https://github.com/run-llama/llama_index/tree/main/docs/examples/agent)\n- 源码仓库：[llama-index-core/agent](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/agent)\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[智能体系统](#agent_system), [查询引擎](#query_engine)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/workflow/workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/workflow.py)\n- [llama-index-core/llama_index/core/workflow/context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/context.py)\n- [llama-index-core/llama_index/core/workflow/events.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/events.py)\n- [llama-index-core/llama_index/core/workflow/handler.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/handler.py)\n\n \n\n# 工作流引擎\n\n## 概述\n\nLlamaIndex 工作流引擎（Workflow Engine）是一个基于事件驱动架构的异步任务编排框架，专为构建复杂的大型语言模型（LLM）应用而设计。该引擎允许开发者通过声明式的方式定义工作流步骤（Step），并通过事件的发布与订阅机制来实现步骤之间的通信与协作。\n\n工作流引擎的核心价值在于解耦应用逻辑，使开发者能够将复杂的 LLM 任务分解为独立的、可复用的步骤，同时保持对这些步骤执行顺序和依赖关系的精确控制。\n\n## 核心架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[Workflow 工作流] --> B[Context 上下文]\n A --> C[Event 事件]\n A --> D[Step 步骤]\n C --> E[StartEvent 启动事件]\n C --> F[StopEvent 停止事件]\n C --> G[CustomEvent 自定义事件]\n D --> H[StartDecorator 启动装饰器]\n D --> I[StepDecorator 步骤装饰器]\n B --> J[State 状态管理]\n J --> K[变量存取]\n B --> L[流式数据处理]\n L --> M[迭代器支持]\n```\n\n### 核心组件\n\n| 组件名称 | 文件位置 | 职责说明 |\n|---------|---------|---------|\n| Workflow | workflow.py | 工作流容器，管理所有步骤和事件路由 |\n| Context | context.py | 提供步骤间的状态共享和数据传递能力 |\n| Event | events.py | 定义事件基类及内置事件类型 |\n| WorkflowHandler | handler.py |管理工作流执行，处理异步任务调度 |\n\n## 事件系统\n\n事件系统是工作流引擎的通信基础，采用发布-订阅模式实现步骤间的松耦合交互。\n\n### 内置事件类型\n\n事件系统定义在 `events.py` 文件中，提供了基础的事件抽象类和预定义事件类型。\n\n```mermaid\ngraph LR\n A[事件发布] --> B[EventBus 事件总线]\n B --> C[Step 步骤处理]\n C --> D[新事件发布]\n D --> B\n```\n\n### 事件类型表\n\n| 事件类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| StartEvent | 工作流启动时触发的事件 | 初始化工作流、传递启动参数 |\n| StopEvent | 工作流停止时触发的事件 | 清理资源、返回最终结果 |\n| CustomEvent | 自定义事件类型 | 步骤间自定义通信 |\n\n事件类采用 Pydantic 模型定义，确保类型安全和序列化能力：\n\n```python\nclass Event(BaseModel):\n \"\"\"基础事件类\"\"\"\n pass\n\nclass StartEvent(Event):\n \"\"\"工作流启动事件\"\"\"\n pass\n\nclass StopEvent(Event):\n \"\"\"工作流停止事件\"\"\"\n pass\n\nclass CustomEvent(Event):\n \"\"\"自定义事件\"\"\"\n name: str\n msg: str = \"\"\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/events.py:1-50]()\n\n## 工作流上下文\n\n上下文（Context）对象在整个工作流执行期间维护状态信息，并提供步骤间数据共享的机制。\n\n### 上下文核心功能\n\n上下文对象提供以下核心能力：\n\n| 功能 | 说明 |\n|-----|------|\n| 状态存储 | 存储和检索工作流执行过程中的数据 |\n| 事件发布 | 允许步骤发布新事件触发后续处理 |\n| 流式处理 | 支持异步迭代器处理流式数据 |\n\n### 上下文 API\n\n```python\nclass Context:\n \"\"\"工作流上下文基类\"\"\"\n \n async def get(self, key: str, default: Any = None) -> Any:\n \"\"\"获取上下文变量\"\"\"\n pass\n \n async def set(self, key: str, value: Any) -> None:\n \"\"\"设置上下文变量\"\"\"\n pass\n \n async def publish_event(self, event: Event) -> None:\n \"\"\"发布事件\"\"\"\n pass\n \n async def stream_output(\n self, \n stream_type: str, \n _id: str, \n iterator: AsyncIterator\n ) -> None:\n \"\"\"流式输出处理\"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/context.py:1-100]()\n\n### 状态管理流程\n\n```mermaid\nsequenceDiagram\n participant Step1 as 步骤1\n participant Context as 上下文\n participant Step2 as 步骤2\n \n Step1->>Context: set(\"result\", data)\n Note over Step1,Context: 存储中间结果\n Step1->>Context: publish_event(CustomEvent)\n Note over Context: 触发后续处理\n Step2->>Context: get(\"result\")\n Note over Step2: 获取前置步骤结果\n```\n\n## 工作流定义\n\n### 步骤装饰器\n\n工作流通过装饰器模式定义步骤，支持灵活的声明式语法。\n\n#### 装饰器类型\n\n| 装饰器 | 说明 | 适用场景 |\n|-------|------|---------|\n| @start | 标记工作流入口点 | 定义初始步骤 |\n| @step | 标记常规处理步骤 | 业务逻辑处理 |\n\n### 工作流类定义\n\n```python\nclass Workflow(BaseModel, ABC):\n \"\"\"工作流基类\"\"\"\n \n def __init__(\n self,\n timeout: Optional[float] = None,\n disable_validation: bool = False,\n **kwargs: Any\n ):\n \"\"\"初始化工作流\n \n Args:\n timeout: 工作流超时时间（秒）\n disable_validation: 是否禁用步骤验证\n \"\"\"\n self.timeout = timeout\n self._steps: List[Any] = []\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/workflow.py:1-100]()\n\n### 工作流示例结构\n\n```mermaid\ngraph TD\n A[@start] --> B[初始化步骤]\n B --> C[处理步骤1]\n C --> D{条件判断}\n D -->|条件A| E[处理步骤2A]\n D -->|条件B| F[处理步骤2B]\n E --> G[聚合步骤]\n F --> G\n G --> H[@stop]\n```\n\n## 工作流处理器\n\nWorkflowHandler 负责管理工作流的实际执行，包括异步调度、错误处理和结果收集。\n\n### 处理器核心职责\n\n| 职责 | 说明 |\n|-----|------|\n| 任务调度 | 管理步骤的执行顺序和并发 |\n| 事件路由 | 将事件分发给对应的步骤处理 |\n| 结果收集 | 收集并汇总工作流执行结果 |\n| 错误传播 | 处理执行过程中的异常 |\n\n### 处理器执行流程\n\n```mermaid\nflowchart TD\n A[创建处理器] --> B{超时检查}\n B -->|未超时| C[获取待处理事件]\n B -->|超时| Z[抛出TimeoutError]\n C --> D{存在待处理事件?}\n D -->|是| E[执行对应步骤]\n D -->|否| F{所有步骤完成?}\n E --> G[产生新事件]\n G --> C\n F -->|是| H[返回结果]\n F -->|否| C\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/handler.py:1-100]()\n\n## 异步执行模型\n\n### 异步迭代器支持\n\n工作流引擎原生支持流式数据处理，允许步骤返回异步迭代器：\n\n```python\nasync def process_stream(self, ctx: Context) -> AsyncIterator[str]:\n \"\"\"处理流式数据\"\"\"\n for chunk in data_source:\n yield chunk\n await ctx.publish_event(StreamChunkEvent(data=chunk))\n```\n\n### 流式输出处理\n\n上下文提供专门的流式输出管理机制：\n\n```python\nasync def stream_output(\n self, \n stream_type: str, \n _id: str, \n iterator: AsyncIterator\n) -> None:\n \"\"\"处理步骤产生的流式输出\n \n Args:\n stream_type: 流类型标识\n _id: 流实例唯一标识\n iterator: 异步迭代器对象\n \"\"\"\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/workflow/context.py:50-80]()\n\n## 使用模式\n\n### 基础工作流定义\n\n```python\nfrom llama_index.core.workflow import Workflow, StartEvent, StopEvent, step\n\nclass MyWorkflow(Workflow):\n @step\n async def start(self, ev: StartEvent) -> StopEvent:\n # 初始化处理\n return StopEvent(result=\"complete\")\n```\n\n### 多步骤工作流\n\n```python\nclass MultiStepWorkflow(Workflow):\n @step\n async def step_a(self, ev: StartEvent) -> StepBEvent:\n result_a = await self.process_a(ev.data)\n return StepBEvent(data=result_a)\n \n @step\n async def step_b(self, ev: StepBEvent) -> StopEvent:\n result = await self.process_b(ev.data)\n return StopEvent(result=result)\n```\n\n### 事件驱动交互\n\n```python\nfrom llama_index.core.workflow import Event\n\nclass DataEvent(Event):\n data: Any\n\nclass EventDrivenWorkflow(Workflow):\n @step\n async def producer(self, ctx: Context, ev: StartEvent):\n for item in data_items:\n await ctx.publish_event(DataEvent(data=item))\n \n @step\n async def consumer(self, ctx: Context, ev: DataEvent):\n result = await self.process(ev.data)\n await ctx.set(\"results\", ctx.get(\"results\", []) + [result])\n```\n\n## 配置选项\n\n### 工作流配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| timeout | float | None | 工作流最大执行时间（秒），None 表示无限制 |\n| disable_validation | bool | False | 是否跳过步骤注册验证 |\n| **kwargs | Any | - | 其他传递给基类的参数 |\n\n### 事件配置\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| name | str | 事件名称标识 |\n| msg | str | 事件携带的消息内容 |\n| data | Any | 事件携带的业务数据 |\n\n## 与 LlamaIndex 生态集成\n\n工作流引擎是 LlamaIndex 核心基础设施的一部分，可与其他组件无缝协作：\n\n| 集成组件 | 集成方式 |\n|---------|---------|\n| LLM 模块 | 通过 @step 装饰的步骤调用 LLM |\n| Reader 模块 | 工作流中使用 Reader 加载外部数据 |\n| Agent 模块 | 工作流可包装 Agent 能力 |\n| Query Pipeline | 与查询管道进行数据交换 |\n\n## 最佳实践\n\n### 1. 步骤粒度设计\n\n保持步骤职责单一，每个步骤应该只完成一个明确的任务。复杂的业务逻辑应该拆分为多个步骤，而不是在一个步骤中完成所有处理。\n\n### 2. 事件命名规范\n\n使用清晰的事件命名约定，例如 `StepACompleteEvent`、`DataProcessedEvent` 等，便于理解工作流的数据流向。\n\n### 3. 状态管理策略\n\n- 仅在上下文存储必要的共享状态\n- 避免在上下文中存储大型对象\n- 使用唯一标识符管理多个数据实例\n\n### 4. 错误处理\n\n```python\n@step\nasync def safe_step(self, ctx: Context, ev: InputEvent) -> OutputEvent:\n try:\n result = await self.unsafe_operation(ev.data)\n return OutputEvent(data=result)\n except Exception as e:\n await ctx.publish_event(ErrorEvent(error=str(e)))\n raise\n```\n\n### 5. 超时控制\n\n```python\nworkflow = MyWorkflow(timeout=60.0) # 60秒超时\nresult = await workflow.run()\n```\n\n## 总结\n\nLlamaIndex 工作流引擎提供了一个强大而灵活的异步任务编排框架，通过事件驱动的设计模式使开发者能够构建复杂的 LLM 应用流程。其核心优势包括：\n\n- **声明式定义**：通过装饰器轻松定义工作流步骤\n- **事件驱动通信**：松耦合的步骤间交互机制\n- **异步执行**：原生支持异步编程模式\n- **状态共享**：上下文对象提供可靠的数据传递\n- **流式处理**：内置异步迭代器支持\n\n工作流引擎的模块化设计使其能够适应各种复杂度的应用场景，从简单的线性处理到复杂的多分支并发工作流都能得到良好支持。\n\n---\n\n\n\n## 查询引擎\n\n### 相关页面\n\n相关主题：[核心组件详解](#core_components)\n\n对不起，我无法完成此请求。\n\n**问题说明：**\n\n您要求基于以下源码文件生成关于\"查询引擎\"的Wiki页面：\n\n- `llama-index-core/llama_index/core/query_engine/retriever_query_engine.py`\n- `llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py`\n- `llama-index-core/llama_index/core/query_engine/flare/base.py`\n- `llama-index-core/llama_index/core/query_engine/knowledge_graph_query_engine.py`\n\n但当前提供的上下文（START_OF_CONTEXT）中**不包含这些文件**。上下文仅包含以下类型的README文件：\n\n| 类型 | 数量 |\n|------|------|\n| Readers集成（Web、Wikipedia、Wordpress等） | 15+ |\n| Tools集成（Moss、Brightdata、Exa） | 3 |\n| 其他集成（Docling、Box、Chroma等） | 若干 |\n\n**缺失的关键内容：**\n\n- 查询引擎的Python实现源码\n- 查询引擎的类定义和方法签名\n- 查询引擎的内部逻辑和架构\n- 配置文件和参数定义\n\n**建议：**\n\n1. 请提供完整的查询引擎源码文件内容\n2. 或者调整Wiki页面主题为当前上下文中实际包含的内容（如\"数据读取器\"或\"Web加载器\"）\n\n根据您提供的指南，我不能凭空编造源码中没有的行为或实现细节。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：run-llama/llama_index\n\n摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。\n\n## 1. 能力坑 · 能力证据存在缺口\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Sandbox install result is missing.\n- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。\n- 建议检查：优先补证或在页面明确标记为未验证。\n- 防护动作：证据缺口未关闭前，quality gate 必须保持不可发布。\n- 证据：evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing.\n\n## 2. 能力坑 · 能力判断依赖假设\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:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 6. 维护坑 · 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:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | 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项目：run-llama/llama_index\n\n摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。\n\n## 1. 能力坑 · 能力证据存在缺口\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Sandbox install result is missing.\n- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。\n- 建议检查：优先补证或在页面明确标记为未验证。\n- 防护动作：证据缺口未关闭前，quality gate 必须保持不可发布。\n- 证据：evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing.\n\n## 2. 能力坑 · 能力判断依赖假设\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:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 6. 维护坑 · 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:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# llama_index - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 llama_index 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LlamaIndex is the leading document agent and OCR platform 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：LlamaIndex 简介。围绕“LlamaIndex 简介”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. system_architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. core_components：核心组件详解。围绕“核心组件详解”模拟一次用户任务，不展示安装或运行结果。\n5. data_ingestion：数据摄取流程。围绕“数据摄取流程”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“LlamaIndex 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system_architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. core_components\n输入：用户提供的“核心组件详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. data_ingestion\n输入：用户提供的“数据摄取流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“LlamaIndex 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system_architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / core_components：Step 4 必须围绕“核心组件详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / data_ingestion：Step 5 必须围绕“数据摄取流程”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/run-llama/llama_index\n- https://github.com/run-llama/llama_index#readme\n- README.md\n- llama-index-core/llama_index/core/__init__.py\n- llama-index-core/README.md\n- docs/examples/vector_stores/SimpleIndexDemo.ipynb\n- docs/src/content/docs/framework/getting_started/installation.mdx\n- docs/src/content/docs/framework/getting_started/starter_example.mdx\n- llama-index-core/llama_index/core/indices/base.py\n- llama-index-core/llama_index/core/query_engine/retriever_query_engine.py\n- llama-index-core/llama_index/core/storage/storage_context.py\n- llama-index-core/llama_index/core/schema.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 llama_index 的核心服务。\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项目：run-llama/llama_index\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install llama-index-core\n```\n\n来源：https://github.com/run-llama/llama_index#readme\n\n## 来源\n\n- repo: https://github.com/run-llama/llama_index\n- docs: https://github.com/run-llama/llama_index#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_9e2ab30b6c4046ec86fff5b1edf66d31"
}