{
"canonical_name": "run-llama/llama_index",
"compilation_id": "pack_e138b15723024a308f31ce0e7b528354",
"created_at": "2026-05-15T22:07:39.271500+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": 7377,
"github_stars": 49262,
"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": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "curated popular coverage category matched project identity"
},
"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": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"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": "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": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1933,
"forks": 7377,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 49262
},
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for run-llama/llama_index.\n\nProject:\n- Name: llama_index\n- Repository: https://github.com/run-llama/llama_index\n- Summary: LlamaIndex is the leading document agent and OCR platform\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: LlamaIndex is the leading document agent and OCR platform\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: LlamaIndex is the leading document agent and OCR platform\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to LlamaIndex. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. core-architecture: Core Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. documents-nodes: Documents and Nodes. Produce one small intermediate artifact and wait for confirmation.\n5. storage-systems: Storage Systems. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- docs/src/content/docs/framework/getting_started/concepts.mdx\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/base/llms/base.py\n- llama-index-core/llama_index/core/base/embeddings/base.py\n- llama-index-core/llama_index/core/base/response/schema.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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": "search",
"name": "llama_index 能力包",
"risk": "可发布",
"slug": "llama-index",
"stars": 49262,
"tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"多角色协作流程",
"开源工具"
],
"thumb": "blue",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/run-llama/llama_index 项目说明书\n\n生成时间：2026-05-15 21:38:00 UTC\n\n## 目录\n\n- [Introduction to LlamaIndex](#introduction)\n- [Quick Start Guide](#quickstart)\n- [Core Architecture](#core-architecture)\n- [Integration Architecture](#integration-architecture)\n- [Documents and Nodes](#documents-nodes)\n- [Storage Systems](#storage-systems)\n- [Query Engines](#query-engines)\n- [Retrieval and Reranking](#retrieval-reranking)\n- [Agent Framework](#agent-framework)\n- [Memory Systems](#memory-systems)\n\n\n\n## Introduction to LlamaIndex\n\n### 相关页面\n\n相关主题：[Core Architecture](#core-architecture), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/run-llama/llama_index/blob/main/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/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/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/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 \n\n# Introduction to LlamaIndex\n\nLlamaIndex is a comprehensive data framework designed for building LLM (Large Language Model) applications. It provides the essential tools, abstractions, and integrations needed to connect custom data sources to LLMs for retrieval-augmented generation (RAG), question-answering systems, and other AI-powered applications.\n\n## Overview\n\nLlamaIndex serves as the foundational layer for building AI applications that require sophisticated data ingestion, indexing, and querying capabilities. The framework enables developers to:\n\n- Ingest data from various sources (PDFs, documents, websites, databases)\n- Process and chunk data into optimal segments for LLM consumption\n- Create vector indices for efficient semantic search\n- Build query engines and retrieval pipelines\n- Integrate with hundreds of external services and model providers\n\n资料来源：[README.md:1-20](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Core Architecture\n\nThe LlamaIndex framework follows a modular architecture with distinct components that work together to provide end-to-end data pipeline capabilities.\n\n### Package Structure\n\nLlamaIndex offers two primary installation methods to accommodate different use cases:\n\n| Package | Description | Use Case |\n|---------|-------------|----------|\n| `llama-index` | Starter package with core + selected integrations | Quick start, common setups |\n| `llama-index-core` | Core package only | Custom, minimal deployments |\n\n资料来源：[README.md:45-55](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n### Import Patterns\n\nThe framework uses a namespaced import system that distinguishes between core modules and integration packages:\n\n```python\n# Core modules (included in llama-index-core)\nfrom llama_index.core.xxx import ClassABC\n\n# Integration modules (from separate packages)\nfrom llama_index.xxx.yyy import SubclassABC\n\n# Concrete examples\nfrom llama_index.core.llms import LLM\nfrom llama_index.llms.openai import OpenAI\n```\n\n资料来源：[README.md:56-68](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Data Flow Architecture\n\nThe following diagram illustrates the typical data flow in a LlamaIndex application:\n\n```mermaid\ngraph TD\n A[Data Sources] --> B[Readers/Loaders]\n B --> C[Documents]\n C --> D[Node Parsers]\n D --> E[Nodes/Chunks]\n E --> F[Vector Index]\n F --> G[Retriever]\n G --> H[Query Engine]\n H --> I[LLM Response]\n \n A1[Web Pages] --> B\n A2[PDFs] --> B\n A3[Databases] --> B\n A4[APIs] --> B\n```\n\n## Key Components\n\n### 1. Document Loaders\n\nDocument loaders (Readers) are responsible for ingesting data from external sources. LlamaIndex provides a vast ecosystem of readers:\n\n| Reader | Purpose | Source |\n|--------|---------|--------|\n| `WikipediaReader` | Load Wikipedia pages | [llama-index-readers-wikipedia](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md) |\n| `WholeSiteReader` | Scrape entire websites | [llama-index-readers-web](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| `DoclingReader` | Parse PDFs, DOCX, HTML | [llama-index-readers-docling](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md) |\n| `RemoteDepthReader` | Extract from URLs recursively | [llama-index-readers-remote-depth](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/README.md) |\n\n#### Wikipedia Reader Example\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-readers-wikipedia/README.md:1-25](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n\n#### Docling Reader Example\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资料来源：[llama-index-readers-docling/README.md:1-30](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n\n### 2. Indices\n\nIndices organize documents for efficient retrieval. LlamaIndex supports both managed indices and customizable self-hosted options.\n\n#### Managed Indices\n\nManaged indices like `VectaraIndex` provide fully hosted solutions:\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\nfrom llama_index.core.schema import Document, MediaResource\n\ndocs = [\n Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"This is test text for Vectara integration.\",\n ),\n ),\n]\nindex = VectaraIndex.from_documents(docs)\n```\n\n资料来源：[llama-index-indices-managed-vectara/README.md:30-50](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n\n### 3. LLM Integrations\n\nLlamaIndex provides integrations with numerous LLM providers through a standardized interface:\n\n```python\n# Example: Contextual LLM Integration\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-llms-contextual/README.md:1-20](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-contextual/README.md)\n\n## Usage Patterns\n\n### Building a Simple RAG Pipeline\n\nThe most common pattern involves loading documents, creating an index, and querying it:\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.docling import DoclingReader\n\n# Step 1: Load documents\nreader = DoclingReader()\ndocuments = reader.load_data(file_path=\"document.pdf\")\n\n# Step 2: Create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Step 3: Query\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"Summarize this document\")\n```\n\n### Retrieval-Only Pattern\n\nFor applications requiring only retrieval without generation:\n\n```python\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"How will users feel about this new tool?\")\n```\n\n资料来源：[llama-index-indices-managed-vectara/README.md:50-65](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n\n### LangChain Integration\n\nLlamaIndex components can be used as tools within LangChain agents:\n\n```python\nfrom langchain.agents import initialize_agent, Tool\nfrom langchain.llms import OpenAI\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.web import WholeSiteReader\n\n# Initialize scraper\nscraper = WholeSiteReader(prefix=\"https://docs.llamaindex.ai/en/stable/\", max_depth=10)\ndocuments = scraper.load_data(base_url=\"https://docs.llamaindex.ai/en/stable/\")\n\n# Create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Define tools\ntools = [\n Tool(\n name=\"Website Index\",\n func=lambda q: index.query(q),\n description=\"Useful for answering questions about text on websites.\",\n ),\n]\n```\n\n资料来源：[llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1-40](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\n## LlamaParse Platform\n\n**LlamaParse** is a complementary platform (separate from the open-source LlamaIndex framework) focused on document agents and agentic OCR:\n\n| Component | Function |\n|-----------|----------|\n| **Parse** | Agentic OCR and document parsing (130+ formats) |\n| **Extract** | Structured data extraction from documents |\n| **Index** | Ingest, index, and RAG pipelines |\n| **Split** | Split large documents into subcategories |\n\n资料来源：[README.md:75-85](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Ecosystem Overview\n\nLlamaIndex maintains an extensive ecosystem with over 300 integration packages available through LlamaHub:\n\n```mermaid\ngraph LR\n subgraph \"Data Sources\"\n Web[Web]\n PDFs[PDFs]\n DB[Databases]\n APIs[APIs]\n end\n \n subgraph \"LlamaIndex Core\"\n Docs[Documents]\n Nodes[Nodes]\n Indices[Indices]\n end\n \n subgraph \"LLM Providers\"\n OpenAI[OpenAI]\n HuggingFace[HF]\n Local[Local Models]\n end\n \n Web --> Docs\n PDFs --> Docs\n DB --> Docs\n APIs --> Docs\n Docs --> Indices\n Indices --> OpenAI\n Indices --> HuggingFace\n Indices --> Local\n```\n\n## Configuration Options\n\n### Common Reader Configuration Parameters\n\n| Parameter | Type | Description | Example |\n|-----------|------|-------------|---------|\n| `file_path` | str | Path to input file/URL | `\"document.pdf\"` |\n| `prefix` | str | URL prefix for filtering | `\"https://example.com/\"` |\n| `max_depth` | int | Maximum recursion depth | `10` |\n| `where` | dict | Metadata filter condition | `{\"category\": \"AI\"}` |\n| `query` | list | Search query text | `[\"search term\"]` |\n\n资料来源：[llama-index-readers-chroma/README.md:1-20](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-chroma/README.md)\n\n## Installation\n\n### Quick Start (Recommended)\n\n```bash\npip install llama-index\n```\n\n### Minimal Installation\n\n```bash\npip install llama-index-core\n```\n\n### Individual Integrations\n\n```bash\npip install llama-index-readers-wikipedia\npip install llama-index-readers-docling\npip install llama-index-llms-openai\n```\n\n## Citation\n\nIf you use LlamaIndex in academic work, cite as:\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-105](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Next Steps\n\nTo continue learning LlamaIndex:\n\n1. **Getting Started** - Follow the [starter example](https://docs.llamaindex.ai/en/stable/getting_started/starter_example.html)\n2. **Concepts** - Understand core concepts like Documents, Nodes, and Indices\n3. **LlamaHub** - Browse [300+ integrations](https://llamahub.ai/) for various data sources and LLM providers\n4. **Examples** - Explore [Jupyter notebooks](https://github.com/run-llama/llama_index/blob/main/docs/examples/) for detailed use cases\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to LlamaIndex](#introduction), [Documents and Nodes](#documents-nodes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-dev/README.md](https://github.com/run-llama/llama_index/blob/main/llama-dev/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/llms/llama-index-llms-mistralai/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-mistralai/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- [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/llms/llama-index-llms-modelscope/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-modelscope/README.md)\n \n\n# Quick Start Guide\n\nThis guide provides a comprehensive introduction to getting started with LlamaIndex, covering environment setup, core installation methods, and essential development workflows.\n\n## Prerequisites\n\nBefore beginning, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Python | 3.8 or higher |\n| Package Manager | `uv` (recommended) or `pip` |\n| Operating System | Unix-like (Linux, macOS), Windows with WSL |\n| Git | Latest stable version |\n\n## Environment Setup\n\n### Creating a Virtual Environment\n\nLlamaIndex recommends using `uv` for dependency management. Create a virtual environment as follows:\n\n```bash\nuv venv\nsource .venv/bin/activate\n```\n\n资料来源：[llama-dev/README.md:11]()\n\n### Installing the Development CLI\n\nThe `llama-dev` CLI tool is the official command-line interface for development, testing, and automation in the LlamaIndex monorepo.\n\nInstall it in editable mode:\n\n```bash\nuv pip install -e .\n```\n\nAfter installation, verify the CLI is available:\n\n```bash\nllama-dev --help\n```\n\n资料来源：[llama-dev/README.md:12-18]()\n\n## Core Concepts\n\n```mermaid\ngraph TD\n A[LlamaIndex Project] --> B[Core Package: llama-index-core]\n A --> C[LLM Integrations]\n A --> D[Reader Integrations]\n A --> E[Callback Integrations]\n B --> F[VectorStoreIndex]\n B --> G[ServiceContext]\n B --> H[Document Loading]\n```\n\nThe LlamaIndex framework consists of several key components:\n\n| Component | Purpose |\n|-----------|---------|\n| `llama-index-core` | Core framework functionality including indexing and querying |\n| LLM Integrations | Connectors for various language model providers |\n| Reader Integrations | Data loaders for different document sources |\n| Callback Integrations | Monitoring and logging capabilities |\n\n## Package Management\n\n### Querying Package Information\n\nView information about specific packages in the monorepo:\n\n```bash\n# Get info for a specific package\nllama-dev pkg info llama-index-core\n\n# Get info for all packages\nllama-dev pkg info --all\n```\n\n### Executing Commands in Package Directories\n\nRun commands within the context of specific packages:\n\n```bash\n# Run a command in a specific package\nllama-dev pkg exec --cmd \"uv sync\" llama-index-core\n\n# Run a command in all packages\nllama-dev pkg exec --cmd \"uv sync\" --all\n\n# Exit at first error\nllama-dev pkg exec --cmd \"uv\" --all --fail-fast\n```\n\n资料来源：[llama-dev/README.md:26-41]()\n\n## Testing\n\n### Running Tests Across the Monorepo\n\nExecute tests for specific packages or across all packages:\n\n```bash\n# Run tests for a specific package\nllama-dev pkg test llama-index-core\n\n# Run tests for all packages\nllama-dev pkg test --all\n```\n\n### Quick Test Verification\n\nAfter making changes, verify core functionality:\n\n```bash\nllama-dev pkg exec --cmd \"python -m pytest\" llama-index-core\n```\n\n## Basic LLM Integration Usage\n\n### Initializing an LLM\n\nDifferent LLM providers follow similar initialization patterns:\n\n```python\nfrom llama_index.llms.ollama import Ollama\n\n# Initialize Ollama LLM\nllm = Ollama(model=\"llama3.1:latest\", request_timeout=120.0)\n```\n\n```python\nfrom llama_index.llms.mistralai import MistralAI\n\nllm = MistralAI(api_key=\"\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:30-35]()\n资料来源：[llama-index-integrations/llms/llama-index-llms-mistralai/README.md:16-18]()\n\n### Generating Completions\n\n```python\n# Simple completion\nresp = llm.complete(\"Who is Paul Graham?\")\nprint(resp)\n```\n\n```python\n# Chat completion with messages\nfrom llama_index.core.llms import ChatMessage\n\nmessages = [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=\"You are a helpful assistant.\"\n ),\n ChatMessage(role=MessageRole.USER, content=\"How to make cake?\"),\n]\nresp = llm.chat(messages)\nprint(resp)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-modelscope/README.md:24-37]()\n\n### Streaming Responses\n\n```python\n# Stream completions\nresp = llm.stream_complete(\"Paul Graham is \")\nfor r in resp:\n print(r.delta, end=\"\")\n```\n\n```python\n# Stream chat responses\nresp = llm.stream_chat([message])\nfor r in resp:\n print(r.delta, end=\"\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-mistralai/README.md:40-48]()\n\n## Building an Index from Documents\n\n### Basic Index Creation\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\n# Create index from documents\nindex = VectorStoreIndex.from_documents(documents)\n```\n\n```python\n# Query the index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"What is the main topic?\")\nprint(response)\n```\n\n### Loading Data from URLs\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\n# Initialize the scraper\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\n# Start scraping from a base URL\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n\n# Create index\nindex = VectorStoreIndex.from_documents(documents)\nindex.query(\"What language is on this website?\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:14-34]()\n\n## Configuration Options\n\n### Key Parameters\n\n| Parameter | Description | Default Value |\n|-----------|-------------|---------------|\n| `model` | LLM model identifier | Required |\n| `api_key` | API key for the provider | Required for cloud providers |\n| `request_timeout` | Request timeout in seconds | 30.0 |\n| `temperature` | Sampling temperature | 0.7 |\n| `max_tokens` | Maximum tokens to generate | Provider-specific |\n| `context_window` | Maximum context length | Provider-specific |\n\n### Environment Variables\n\nSet API keys as environment variables before initialization:\n\n```bash\nexport KONKO_API_KEY=\nexport OPENAI_API_KEY=\n```\n\n```python\nimport os\nos.environ[\"KONKO_API_KEY\"] = \"\"\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-konko/README.md:15-20]()\n\n## Common Workflows\n\n```mermaid\ngraph LR\n A[Setup Environment] --> B[Install llama-dev]\n B --> C[Explore Packages]\n C --> D{Development Goal}\n D -->|Testing| E[Run Tests]\n D -->|Integration| F[Configure LLM]\n D -->|Data Loading| G[Set up Readers]\n E --> H[Modify Code]\n F --> H\n G --> H\n H --> I[Verify Changes]\n I --> E\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| CLI not found | Ensure virtual environment is activated |\n| API key errors | Verify environment variables are set |\n| Package import errors | Run `uv sync` in the package directory |\n| Timeout errors | Increase `request_timeout` parameter |\n\n### Verification Commands\n\n```bash\n# Check installation\nllama-dev --version\n\n# Verify package structure\nllama-dev pkg info --all\n\n# Test core imports\npython -c \"import llama_index; print(llama_index.__version__)\"\n```\n\n## Next Steps\n\nAfter completing this quick start guide:\n\n1. Explore specific [LLM integrations](#core-llm-integrations) for your preferred provider\n2. Review [reader integrations](#data-loading) for your data sources\n3. Study the [core API documentation](#key-concepts) for advanced indexing strategies\n4. Join the community for support and updates\n\n---\n\n\n\n## Core Architecture\n\n### 相关页面\n\n相关主题：[Introduction to LlamaIndex](#introduction), [Integration Architecture](#integration-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/base/llms/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/llms/base.py)\n- [llama-index-core/llama_index/core/base/embeddings/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/embeddings/base.py)\n- [llama-index-core/llama_index/core/base/response/schema.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/response/schema.py)\n- [llama-index-core/llama_index/core/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/types.py)\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/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/node_parser/node.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/node.py)\n- [llama-index-core/llama_index/core/response/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/response/__init__.py)\n \n\n# Core Architecture\n\n## Overview\n\nLlamaIndex is a data framework for building LLM-powered applications. The Core Architecture establishes the fundamental building blocks that enable developers to connect large language models with their custom data sources. This architectural foundation provides a layered, modular approach where each component—from language model interfaces to response handling—follows consistent patterns and abstractions.\n\nThe core architecture serves as the abstraction layer between raw data ingestion and sophisticated LLM-powered querying. It separates concerns by defining clear interfaces for language models (LLMs), embedding services, document processing, indexing, and response generation. This design allows developers to swap implementations, extend functionality, and maintain clean separation between components.\n\n## System Components\n\n### High-Level Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph \"Data Layer\"\n Documents[Documents]\n Nodes[Nodes]\n Index[Index]\n end\n \n subgraph \"Core Abstractions\"\n LLMs[LLM Base]\n Embeddings[Embedding Base]\n Response[Response Schema]\n end\n \n subgraph \"Service Layer\"\n VectorStore[Vector Store]\n StorageContext[Storage Context]\n end\n \n subgraph \"Application Layer\"\n Query[Query Engine]\n Chat[Chat Engine]\n Agent[Agent]\n end\n \n Documents --> NodeParser\n NodeParser --> Nodes\n Nodes --> Index\n Index --> Query\n Query --> Response\n LLMs --> Query\n Embeddings --> Index\n```\n\n## Language Model (LLM) Abstraction\n\n### Purpose and Role\n\nThe LLM base abstraction (`llama_index.core.base.llms.base`) defines the contract that all language model implementations must follow. This abstraction enables LlamaIndex to support multiple LLM providers—including OpenAI, Anthropic, local models, and custom implementations—through a unified interface.\n\n资料来源：[llama-index-core/llama_index/core/base/llms/base.py:1-50]()\n\n### Base LLM Interface\n\nThe `LLM` base class provides the following core methods:\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `complete()` | Synchronous text completion | `prompt: str`, `formatted: bool = False`, `**kwargs` |\n| `stream_complete()` | Streaming text completion | `prompt: str`, `formatted: bool = False`, `**kwargs` |\n| `chat()` | Synchronous chat completion | `messages: List[ChatMessage]`, `**kwargs` |\n| `stream_chat()` | Streaming chat completion | `messages: List[ChatMessage]`, `**kwargs` |\n\n### LLM Class Hierarchy\n\n```mermaid\nclassDiagram\n class LLM {\n <>\n +complete()\n +stream_complete()\n +chat()\n +stream_chat()\n +metadata: LLMMetadata\n }\n \n class LLMMetadata {\n +model: str\n +temperature: float\n +top_p: int\n +max_tokens: Optional[int]\n +context_window: int\n +is_chat_model: bool\n +is_function_calling_model: bool\n }\n \n class ChatMessage {\n +role: MessageRole\n +content: str\n +additional_kwargs: Dict\n }\n \n LLM --> LLMMetadata\n LLM --> ChatMessage\n```\n\n资料来源：[llama-index-core/llama_index/core/base/llms/base.py:50-120]()\n\n### Message Roles\n\nThe `MessageRole` enum defines valid roles for chat messages:\n\n| Role | Description |\n|------|-------------|\n| `SYSTEM` | System-level instructions |\n| `USER` | User-generated content |\n| `ASSISTANT` | Model-generated responses |\n| `FUNCTION` | Function call results |\n\n## Embedding Abstraction\n\n### Purpose and Role\n\nThe embedding base (`llama_index.core.base.embeddings.base`) provides the interface for text vectorization. Embeddings transform textual content into numerical vectors that enable semantic similarity searches. This abstraction supports various embedding providers while maintaining a consistent API.\n\n资料来源：[llama-index-core/llama_index/core/base/embeddings/base.py:1-60]()\n\n### Embedding Interface Methods\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `get_query_embedding()` | Embed a single query string | `List[float]` |\n| `get_text_embedding()` | Embed a single text string | `List[float]` |\n| `get_text_embedding_batch()` | Embed multiple texts in batch | `List[List[float]]` |\n| `get_query_embedding_batch()` | Embed multiple queries in batch | `List[List[float]]]` |\n\n### Embedding Configuration\n\n```mermaid\ngraph LR\n A[Text Input] --> B[Embedding Model]\n B --> C[Dimension: 384-1536]\n C --> D[Normalized Vector]\n```\n\n资料来源：[llama-index-core/llama_index/core/base/embeddings/base.py:60-100]()\n\n## Response Schema\n\n### Purpose and Role\n\nThe response schema (`llama_index.core.base.response.schema`) defines the data structures used throughout LlamaIndex for returning query results, streaming responses, and structured outputs. This ensures consistent response handling across different query types and engines.\n\n资料来源：[llama-index-core/llama_index/core/base/response/schema.py:1-80]()\n\n### Core Response Models\n\n| Class | Purpose |\n|-------|---------|\n| `Response` | Wraps text responses with sources |\n| `StreamingResponse` | Handles streaming token outputs |\n| `ResponseMode` | Enum for response generation modes |\n| `Sources` | Container for source nodes and metadata |\n\n### Response Mode Enumeration\n\n```mermaid\ngraph TD\n A[Query] --> B{Response Mode}\n B --> C[default]\n B --> D[refine]\n B --> E[compact]\n B --> F[accumulate]\n B --> G[compact_accumulate]\n \n C --> H[Single pass response]\n D --> I[Iterative refinement]\n E --> J[Compact and respond]\n F --> K[Aggregate node responses]\n G --> L[Compact then accumulate]\n```\n\n资料来源：[llama-index-core/llama_index/core/base/response/schema.py:30-50]()\n\n## Core Types System\n\n### Type Definitions\n\nThe types module (`llama_index.core.types`) defines foundational enumerations and type aliases used throughout the framework:\n\n| Type | Description |\n|------|-------------|\n| `ModelType` | Defines model categories (e.g., `LLM`, `EMBEDDING`) |\n| `PromptType` | Categorizes prompts (e.g., `SUMMARY`, `QUERY`) |\n| `NodeType` | Defines node kinds (e.g., `TEXT`, `DOCUMENT`) |\n\n资料来源：[llama-index-core/llama_index/core/types.py:1-60]()\n\n### Node Parser Types\n\n```mermaid\nclassDiagram\n class Node {\n <>\n +id_: str\n +embedding: Optional[List[float]]\n +metadata: Dict[str, Any]\n +relationships: Dict[NodeRelationship, Node]\n +excluded_embed_metadata_keys: List[str]\n +excluded_llm_metadata_keys: List[str]\n }\n \n class TextNode {\n +text: str\n +start_char_idx: Optional[int]\n +end_char_idx: Optional[int]\n }\n \n class Document {\n +text: str\n +doc_id: str\n +embedding: Optional[List[float]]\n }\n \n Node <|-- TextNode\n Node <|-- Document\n```\n\n## Document and Node Model\n\n### Document Structure\n\nDocuments represent the top-level container for source data. Each document contains metadata and can be broken down into smaller nodes for indexing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `doc_id` | `str` | Unique document identifier |\n| `text` | `str` | Full text content |\n| `metadata` | `Dict[str, Any]` | Associated metadata |\n| `embedding` | `Optional[List[float]]` | Pre-computed embedding |\n\n### Node Relationships\n\nNodes maintain relationships with other nodes through the `NodeRelationship` enum:\n\n| Relationship | Description |\n|--------------|-------------|\n| `SOURCE` | Parent document relationship |\n| `PREVIOUS` | Previous sibling node |\n| `NEXT` | Next sibling node |\n| `PARENT` | Parent node in hierarchy |\n| `CHILD` | Child node in hierarchy |\n\n资料来源：[llama-index-core/llama_index/core/node_parser/node.py:30-80]()\n\n## Storage Architecture\n\n### Storage Context\n\nThe `StorageContext` manages persistence layers for various data components:\n\n```mermaid\ngraph TD\n StorageContext --> VectorStore\n StorageContext --> DocStore\n StorageContext --> IndexStore\n StorageContext --> GraphStore\n \n VectorStore --> Milvus[Milvus]\n VectorStore --> Chroma[Chroma]\n VectorStore --> Pinecone[Pinecone]\n \n DocStore --> MongoDB[MongoDB]\n DocStore --> Redis[Redis]\n DocStore --> Simple[SimpleKVStore]\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py:1-50]()\n\n### Storage Components\n\n| Component | Purpose |\n|-----------|---------|\n| `vector_store` | Stores embedding vectors for similarity search |\n| `doc_store` | Stores serialized nodes and documents |\n| `index_store` | Stores index metadata and configurations |\n| `graph_store` | Stores knowledge graph relationships |\n\n## Index Architecture\n\n### Base Index Structure\n\nIndexes provide the mechanism for organizing and querying documents. The base index class establishes the contract for all index implementations:\n\n```mermaid\ngraph LR\n A[Documents] --> B[Index Construction]\n B --> C[Node Parsing]\n C --> D[Embedding Generation]\n D --> E[Vector Storage]\n E --> F[Queryable Index]\n```\n\n### Index Types\n\n| Index Type | Use Case |\n|------------|----------|\n| `VectorStoreIndex` | Semantic search over embeddings |\n| `SummaryIndex` | Document summarization |\n| `KeywordTableIndex` | Keyword-based retrieval |\n| `KnowledgeGraphIndex` | Graph-based knowledge representation |\n\n资料来源：[llama-index-core/llama_index/core/indices/base.py:1-80]()\n\n## Query Engine Architecture\n\n### Query Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant QueryEngine\n participant Retriever\n participant LLM\n participant Response\n \n User->>QueryEngine: Query Request\n QueryEngine->>Retriever: Retrieve Nodes\n Retriever-->>QueryEngine: Source Nodes\n QueryEngine->>LLM: Synthesize Response\n LLM-->>QueryEngine: Response\n QueryEngine->>Response: Format Output\n Response-->>User: Formatted Answer\n```\n\n### Retriever Types\n\n| Retriever | Description |\n|-----------|-------------|\n| `VectorRetriever` | Embedding-based similarity search |\n| `KeywordRetriever` | BM25 or keyword matching |\n| `HybridRetriever` | Combined vector and keyword search |\n| `SentenceWindowRetriever` | Contextual window retrieval |\n\n## Configuration and Extensibility\n\n### Service Context\n\nThe `ServiceContext` bundles together the core service components:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `llm` | `LLM` | `OpenAI()` | Language model instance |\n| `embed_model` | `Embedding` | `OpenAIEmbedding()` | Embedding model instance |\n| `node_parser` | `NodeParser` | `SentenceSplitter()` | Text chunking strategy |\n| `prompt_helper` | `PromptHelper` | Auto-calculated | Prompt size optimization |\n\n### Customization Patterns\n\n```mermaid\ngraph TD\n subgraph \"Extension Points\"\n CustomLLM[Custom LLM Implementation]\n CustomEmbed[Custom Embedding Model]\n CustomParser[Custom Node Parser]\n CustomStore[Custom Storage Backend]\n end\n \n CustomLLM -->|inherits| LLMBase[LLM Base]\n CustomEmbed -->|inherits| EmbedBase[Embedding Base]\n CustomParser -->|inherits| NodeParserBase[NodeParser Base]\n CustomStore -->|inherits| StorageContextBase[StorageContext Base]\n```\n\n## Summary\n\nThe Core Architecture of LlamaIndex establishes a modular, extensible framework built on well-defined abstractions. The layered architecture—from base interfaces like `LLM` and `Embedding` through storage and indexing components to application-layer query engines—enables developers to:\n\n1. **Swap implementations** without changing application code\n2. **Extend functionality** through inheritance and composition\n3. **Maintain clean separation** between concerns\n4. **Support multiple providers** through unified interfaces\n\nThe architecture follows consistent patterns across components, making the framework predictable and learnable while supporting the diverse requirements of production LLM applications.\n\n---\n\n## See Also\n\n- [LLM Integrations](../llms/README.md)\n- [Embedding Integrations](../embeddings/README.md)\n- [Index Examples](../examples/index.md)\n- [Storage Integrations](../storage/README.md)\n\n---\n\n\n\n## Integration Architecture\n\n### 相关页面\n\n相关主题：[Core Architecture](#core-architecture), [Retrieval and Reranking](#retrieval-reranking)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-integrations/readers/llama-index-readers-preprocess/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-preprocess/README.md)\n- [llama-index-integrations/readers/llama-index-readers-remote-depth/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/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/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- [llama-index-integrations/llms/llama-index-llms-lmstudio/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-lmstudio/README.md)\n- [llama-index-integrations/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n- [llama-index-integrations/llms/llama-index-llms-langchain/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-langchain/README.md)\n \n\n# Integration Architecture\n\n## Overview\n\nLlamaIndex employs a modular integration architecture that extends the core framework's capabilities through a comprehensive ecosystem of pluggable components. The integration system allows developers to connect LlamaIndex with external services, APIs, local models, and specialized tools without modifying the core library. This architecture follows a provider-based pattern where each integration package implements standardized interfaces to ensure compatibility and consistent behavior across different external systems.\n\nThe integration architecture serves as the bridge between LlamaIndex's core data structures and the diverse landscape of LLM providers, embedding services, document loaders, and auxiliary tools. By maintaining well-defined contracts between components, the system enables seamless swapping of implementations while preserving the overall workflow of building retrieval-augmented generation (RAG) pipelines and query engines.\n\n## Integration Categories\n\nLlamaIndex organizes its integrations into distinct categories, each addressing a specific aspect of the LLM application development workflow. The categorization ensures logical separation of concerns and simplifies dependency management for end users.\n\n### LLM Integrations\n\nLLM (Large Language Model) integrations provide adapters for connecting to various language model providers. These integrations implement the unified LLM interface defined in `llama_index.core.llms`, allowing developers to switch between providers without changing application code. Each LLM integration handles provider-specific authentication, request formatting, response parsing, and streaming behavior.\n\n| Integration Package | Provider | Key Features |\n|---------------------|----------|--------------|\n| `llama-index-llms-contextual` | Contextual | Contextual LLM wrapper |\n| `llama-index-llms-konko` | Konko | Supports both Konko and OpenAI models |\n| `llama-index-llms-lmstudio` | LM Studio | Local server integration |\n| `llama-index-llms-monsterapi` | MonsterAPI | Private deployments and GA models |\n| `llama-index-llms-modelscope` | ModelScope | Qwen and other ModelScope models |\n| `llama-index-llms-langchain` | LangChain | LangChain LLM wrapper |\n| `llama-index-llms-optimum-intel` | Intel Optimum | CPU-optimized inference |\n\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\n### Reader Integrations\n\nReader integrations enable data ingestion from various document sources and web content. These loaders transform external data formats into LlamaIndex's internal `Document` schema, providing a unified representation regardless of the source type.\n\n| Reader Type | Source Format | Package |\n|-------------|---------------|---------|\n| Document Readers | PDF, DOCX, HTML | `llama-index-readers-docling` |\n| Web Readers | URLs, Articles | `llama-index-readers-web` |\n| Wikipedia | Wikipedia pages | `llama-index-readers-wikipedia` |\n| Remote Content | Deep link crawling | `llama-index-readers-remote-depth` |\n| Cloud Storage | Box files | `llama-index-readers-box` |\n| Preprocessed | Chunks from Preprocess API | `llama-index-readers-preprocess` |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n\n### Embedding Integrations\n\nEmbedding integrations provide vectorization capabilities through external embedding models. These components convert text into dense vector representations suitable for semantic search and similarity operations.\n\n| Provider | Model Examples | Package |\n|----------|---------------|---------|\n| Ollama | `nomic-embed-text`, `embeddinggemma`, `mxbai-embed-large` | `llama-index-embeddings-ollama` |\n\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### Index Integrations\n\nIndex integrations connect to managed vector search services, providing fully-hosted indexing and retrieval capabilities. These integrations abstract the complexity of distributed vector databases behind LlamaIndex's retriever interface.\n\n| Managed Service | Package | Features |\n|-----------------|---------|----------|\n| Vectara | `llama-index-indices-managed-vectara` | RAG pipeline, retriever, query engine |\n\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\n### Tool Integrations\n\nTool integrations extend LlamaIndex's agent capabilities by providing access to external services that can be invoked during agent execution.\n\n| Tool Provider | Features | Package |\n|---------------|----------|---------|\n| Moss | Hybrid search (keyword + semantic) | `llama-index-tools-moss` |\n\n### Callback Integrations\n\nCallback integrations enable observability and feedback collection by integrating with external monitoring and evaluation platforms.\n\n| Platform | Purpose | Package |\n|----------|---------|---------|\n| Argilla | Feedback loop, LLM monitoring | `llama-index-callbacks-argilla` |\n\n资料来源：[llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md)\n\n## System Architecture\n\nThe integration architecture follows a layered approach where core abstractions define the contracts, and integration packages provide concrete implementations. This design enables horizontal scalability of integrations while maintaining vertical consistency with the core framework.\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[Core LlamaIndex]\n B --> C[Interface Abstractions]\n C --> D[LLM Abstraction]\n C --> E[Reader Abstraction]\n C --> F[Embedding Abstraction]\n C --> G[Retriever Abstraction]\n D --> H[LLM Integrations]\n E --> I[Reader Integrations]\n F --> J[Embedding Integrations]\n G --> K[Index Integrations]\n H --> L[Konko, LMStudio, MonsterAPI, etc.]\n I --> M[Docling, Wikipedia, Web, Box, etc.]\n J --> N[Ollama Embeddings]\n K --> O[Vectara]\n```\n\n## Common Integration Patterns\n\n### LLM Integration Pattern\n\nLLM integrations follow a consistent initialization pattern that accepts provider-specific configuration parameters. The typical constructor accepts a model identifier, base URL for API endpoints, and optional generation parameters such as temperature and maximum tokens.\n\n```python\nfrom llama_index.llms.provider_name import ProviderLLM\n\nllm = ProviderLLM(\n model=\"model-identifier\",\n api_key=\"your-api-key\",\n temperature=0.7,\n max_tokens=256\n)\n```\n\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### Reader Integration Pattern\n\nReader integrations follow a loader pattern where initialization may require credentials, and the `load_data` method accepts source-specific parameters such as URLs, file paths, or query filters.\n\n```python\nfrom llama_index.readers.source_type import SourceReader\n\nreader = SourceReader(credentials=\"your-credentials\")\ndocuments = reader.load_data(source=\"document-source\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-remote-depth/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/README.md)\n\n## Data Flow Architecture\n\nThe integration architecture enables a complete RAG pipeline where each component plays a specific role in transforming input data into actionable insights.\n\n```mermaid\ngraph LR\n A[Document Sources] --> B[Readers]\n B --> C[Documents]\n C --> D[Node Parsers]\n D --> E[Nodes]\n E --> F[Vector Index]\n E --> G[Storage Context]\n F --> H[Retriever]\n G --> H\n H --> I[Query Engine]\n I --> J[LLM]\n J --> K[Response]\n```\n\n## Installation and Dependency Management\n\nEach integration package follows the naming convention `llama-index-{category}-{provider}` and can be installed independently via pip. This modular approach minimizes dependency overhead by allowing users to install only the packages required for their specific use case.\n\n| Category | Package Naming Pattern | Installation Command |\n|----------|----------------------|---------------------|\n| LLM | `llama-index-llms-{provider}` | `pip install llama-index-llms-{provider}` |\n| Reader | `llama-index-readers-{source}` | `pip install llama-index-readers-{source}` |\n| Embedding | `llama-index-embeddings-{provider}` | `pip install llama-index-embeddings-{provider}` |\n| Index | `llama-index-indices-{type}-{provider}` | `pip install llama-index-indices-{type}-{provider}` |\n| Tool | `llama-index-tools-{provider}` | `pip install llama-index-tools-{provider}` |\n| Callback | `llama-index-callbacks-{platform}` | `pip install llama-index-callbacks-{platform}` |\n\n## Configuration Management\n\nIntegrations typically support configuration through both constructor parameters and environment variables. This dual approach accommodates both explicit configuration in code and secret management through environment-based configuration.\n\n### Environment Variable Pattern\n\nMany integrations follow a pattern where API keys can be set as environment variables for security and convenience:\n\n```bash\nexport PROVIDER_API_KEY=\"your-api-key\"\nexport OPENAI_API_KEY=\"your-openai-key\"\n```\n\n### Constructor Parameter Pattern\n\nAlternatively, credentials can be passed directly to the integration constructor:\n\n```python\nllm = ProviderLLM(\n model=\"model-name\",\n api_key=\"explicit-api-key\",\n base_url=\"https://api.provider.com\"\n)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-lmstudio/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-lmstudio/README.md)\n\n## Extending the Architecture\n\nThe integration architecture is designed for extensibility. New integrations can be created by implementing the appropriate abstract base classes defined in `llama_index.core`. Each integration category has its own interface specification that ensures consistency across implementations.\n\n### Creating a New LLM Integration\n\nTo create a new LLM integration, implement the following interface contract:\n\n1. Inherit from the base LLM class\n2. Implement `complete()`, `chat()`, and streaming methods\n3. Handle provider-specific authentication and error handling\n4. Follow the naming convention for the package\n\n### Creating a New Reader Integration\n\nTo create a new reader integration:\n\n1. Implement a loader class with `load_data()` method\n2. Transform source data into `Document` objects\n3. Handle pagination, filtering, and error cases appropriately\n4. Document supported source formats and parameters\n\n## Integration Testing Considerations\n\nEach integration package maintains its own test suite to verify compatibility with the external service. Integration tests typically require actual API credentials and network access, distinguishing them from unit tests that mock external dependencies.\n\n## Best Practices\n\nWhen working with LlamaIndex integrations, consider the following best practices:\n\n1. **Dependency Isolation**: Install only required integration packages to minimize potential conflicts\n2. **Credential Management**: Use environment variables for sensitive credentials in production\n3. **Error Handling**: Implement appropriate retry logic and fallback strategies for external service calls\n4. **Resource Management**: Close connections and release resources properly when using streaming responses\n5. **Version Compatibility**: Check integration package versions against the core LlamaIndex version for compatibility\n\n## Deprecated Integrations\n\nSome integration packages may be discontinued over time as external services evolve or change their offerings. When an integration is deprecated, it will receive no further updates or support. Users should migrate to alternative solutions before removing deprecated packages from their projects.\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-preprocess/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-preprocess/README.md)\n\n## Conclusion\n\nThe integration architecture provides a flexible, extensible framework for connecting LlamaIndex with the broader ecosystem of LLM providers, data sources, and tools. By maintaining standardized interfaces while allowing provider-specific implementations, the architecture enables developers to build sophisticated RAG applications without being locked into a single vendor or service. The modular design supports incremental adoption, allowing teams to integrate new capabilities as their requirements evolve.\n\n---\n\n\n\n## Documents and Nodes\n\n### 相关页面\n\n相关主题：[Storage Systems](#storage-systems), [Query Engines](#query-engines)\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/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/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/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-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/node_parser/llama-index-node-parser-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/node_parser/llama-index-node-parser-docling/README.md)\n \n\n# Documents and Nodes\n\n## Overview\n\nIn LlamaIndex, **Documents** and **Nodes** are the fundamental data structures that represent information to be indexed, searched, and retrieved. Documents serve as the primary unit of input data, while Nodes are the granular chunks created during document processing for optimal embedding and retrieval.\n\n## Document Model\n\n### Purpose and Scope\n\nA Document in LlamaIndex represents a single unit of data to be indexed. It encapsulates the content along with associated metadata that provides context about the source, type, and additional information useful for retrieval and processing.\n\n### Core Document Schema\n\nThe Document model is defined in `llama-index-core/llama_index/core/schema.py` and includes the following key attributes:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `text` | str | The main text content of the document |\n| `id_` | str | Unique identifier for the document |\n| `metadata` | Dict[str, Any] | Additional metadata about the document |\n| `mimetype` | str | MIME type of the document content |\n| `relationships` | Dict[str, RelationshipType] | Relationships to other nodes/documents |\n\n### Document Construction\n\nDocuments can be created with varying levels of detail:\n\n```python\nfrom llama_index.core import Document\n\n# Basic document\ndoc = Document(text=\"Your content here\")\n\n# Document with metadata\ndoc = Document(\n text=\"Your content here\",\n metadata={\n \"source\": \"review.txt\",\n \"author\": \"John Doe\",\n \"date\": \"2024-01-15\"\n }\n)\n```\n\n## Node Model\n\n### Purpose and Scope\n\nNodes are the result of parsing and chunking Documents into smaller, semantically coherent pieces. Each Node inherits document-like properties but adds relationship information linking back to its parent Document and sibling Nodes.\n\n### Node Structure\n\nNodes extend the Document schema with additional attributes defined in `llama-index-core/llama_index/core/schema.py`:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `node_id` | str | Unique identifier for the node |\n| `start_char_idx` | int | Starting character index in parent document |\n| `end_char_idx` | int | Ending character index in parent document |\n| `text_template` | str | Template for rendering the node text |\n| `relationships` | Dict[RelationshipType, RelatedNodeType] | Relationships including PARENT, PREVIOUS, NEXT |\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[Raw Input Data] --> B[Document]\n B --> C[Node Parser]\n C --> D[Nodes]\n D --> E[Embedding Model]\n E --> F[Vector Index]\n \n G[Metadata] --> B\n H[Relationships] --> D\n \n B -->|PARENT| D\n D -->|CHILD| B\n```\n\n## Readers and Loading\n\n### Base Reader Interface\n\nReaders are responsible for loading data from various sources and converting them into Documents. The base reader interface is defined in `llama-index-core/llama_index/core/readers/base.py`.\n\n| Method | Description |\n|--------|-------------|\n| `load_data()` | Load documents from a data source |\n| `lazy_load_data()` | Lazily load documents for memory efficiency |\n\n### Supported Reader Types\n\nLlamaIndex provides numerous reader integrations for different data sources:\n\n| Category | Reader | Description |\n|----------|--------|-------------|\n| Document | Docling Reader | PDF, DOCX, HTML extraction to Markdown or JSON |\n| Document | MarkItDown Reader | Converts various formats to Markdown |\n| Document | Docugami Loader | XML knowledge graph from PDF/DOCX |\n| Web | NewsArticleReader | Parses news article URLs |\n| Web | UnstructuredURLLoader | URL text extraction via Unstructured.io |\n| Web | TrafilaturaWebReader | Web scraping with trafilatura |\n| Web | MainContentExtractorReader | Main content extraction from websites |\n| Web | ReadabilityWebPageReader | Readability-based web extraction |\n| Web | RemoteDepthReader | Recursive URL loading with depth control |\n| Web | WholeSiteReader | Full site scraping with prefix/depth |\n| Academic | SemanticScholarReader | Scholarly articles and papers |\n| Database | Chroma Reader | Loading from Chroma vector store |\n\n### Usage Example\n\n```python\nfrom llama_index.readers.docling import DoclingReader\n\nreader = DoclingReader()\ndocs = reader.load_data(file_path=\"document.pdf\")\n```\n\n## Node Parsers\n\n### Purpose and Scope\n\nNode Parsers transform Documents into Nodes by splitting content based on semantic boundaries. The interface is defined in `llama-index-core/llama_index/core/node_parser/interface.py`.\n\n### Core Interface Methods\n\n| Method | Description |\n|--------|-------------|\n| `get_nodes_from_documents()` | Parse documents into nodes |\n| `get_batch_nodes()` | Process documents in batches |\n\n### Sentence Splitter Parser\n\nThe sentence-based node parser in `llama-index-core/llama_index/core/node_parser/text/sentence.py` provides configurable text chunking:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `separator` | str | \"\\n\\n\" | Chunk separator |\n| `chunk_size` | int | 1024 | Maximum characters per chunk |\n| `chunk_overlap` | int | 0 | Overlap between chunks |\n| `chunking_tokenizer` | callable | None | Custom tokenizer function |\n| `callback_manager` | CallbackManager | None | Event callbacks |\n\n### Docling Node Parser\n\nThe Docling Node Parser (`llama-index-integrations/node_parser/llama-index-node-parser-docling/README.md`) parses Docling JSON output into LlamaIndex nodes with rich metadata:\n\n```python\nfrom llama_index.node_parser.docling import DoclingNodeParser\n\nnode_parser = DoclingNodeParser()\nnodes = node_parser.get_nodes_from_documents(documents=docs)\n```\n\n## Document-Node Relationships\n\n### Relationship Types\n\nNodes maintain typed relationships to other components:\n\n| Relationship | Description |\n|--------------|-------------|\n| `PARENT` | Link to parent Document |\n| `CHILD` | Link to child elements |\n| `PREVIOUS` | Previous sibling Node |\n| `NEXT` | Next sibling Node |\n| `SOURCE` | Source Document reference |\n\n### Metadata Preservation\n\nNodes automatically inherit and extend document metadata:\n\n```python\n# Node metadata includes provenance information\n{\n 'doc_items': [{'self_ref': '#/main-text/21'}],\n 'prov': [{'page_no': 2, 'bbox': {...}}],\n 'headings': ['2 Getting Started']\n}\n```\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Load Data] --> B[Create Document]\n B --> C[Parse Document]\n C --> D[Generate Nodes]\n D --> E[Create Embeddings]\n E --> F[Build Index]\n \n A1[Readers] --> A\n C1[Node Parsers] --> C\n```\n\n## Best Practices\n\n### Document Creation\n\n1. Always assign unique `id_` attributes for tracking\n2. Include comprehensive metadata for filtering\n3. Specify `mimetype` when content type matters\n\n### Node Parsing\n\n1. Choose appropriate `chunk_size` for your embedding model\n2. Configure `chunk_overlap` for context continuity\n3. Use semantic-aware parsers (Docling) for complex documents\n\n### Memory Management\n\n1. Use `lazy_load_data()` for large document collections\n2. Consider batch processing for node parsing\n3. Leverage streaming for very large files\n\n## Related Integrations\n\n| Integration | Use Case |\n|-------------|----------|\n| VectaraIndex | Managed semantic search |\n| ChromaReader | Vector database loading |\n| AlibabaCloud AISearch | Cloud-based document parsing |\n| Ollama Embeddings | Local embedding generation |\n\n## Summary\n\nDocuments serve as the primary data ingestion point in LlamaIndex, encapsulating raw content and metadata from various sources. Nodes are the processed, chunked representations optimized for embedding generation and retrieval. Together with Readers and Node Parsers, they form the foundation of the LlamaIndex data pipeline.\n\n---\n\n\n\n## Storage Systems\n\n### 相关页面\n\n相关主题：[Documents and Nodes](#documents-nodes), [Retrieval and Reranking](#retrieval-reranking)\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/storage/docstore/simple_docstore.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/simple_docstore.py)\n- [llama-index-core/llama_index/core/storage/index_store/simple_index_store.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/index_store/simple_index_store.py)\n- [llama-index-core/llama_index/core/storage/chat_store/simple_chat_store.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/chat_store/simple_chat_store.py)\n \n\n# Storage Systems\n\n## Overview\n\nLlamaIndex provides a comprehensive storage system that allows users to persist indexes, documents, and chat histories to disk for later retrieval and reuse. The storage architecture is built around the `StorageContext` class, which serves as the central coordinator for managing various storage backends including document stores, index stores, and chat stores.\n\nThe storage system enables:\n\n- **Persistence**: Save index data to disk for long-term storage\n- **Retrieval**: Reload previously persisted indexes without recomputation\n- **In-memory fallback**: Default in-memory storage when persistence is not configured\n- **Customizable backends**: Pluggable storage implementations for different use cases\n\n## Architecture\n\n```mermaid\ngraph TD\n A[StorageContext] --> B[VectorStore]\n A --> C[DocStore]\n A --> D[IndexStore]\n A --> E[ChatStore]\n A --> F[ImageStore]\n A --> G[GraphStore]\n \n C --> H[SimpleDocStore]\n C --> I[MongoDocStore]\n C --> J[KVDocStore]\n \n D --> K[SimpleIndexStore]\n D --> L[MongoIndexStore]\n D --> M[KVIndexStore]\n \n E --> N[SimpleChatStore]\n E --> O[MongoChatStore]\n```\n\n## StorageContext\n\nThe `StorageContext` class is the main entry point for configuring storage in LlamaIndex. It aggregates all storage components and provides methods for persistence and retrieval.\n\n### Initialization\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# Create with default in-memory stores\nstorage_context = StorageContext.from_defaults()\n\n# Create with persistence to disk\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\n\n# Load existing index from disk\nindex = load_index_from_storage(storage_context=storage_context)\n```\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `persist_dir` | `str` | `None` | Directory path for persistence |\n| `vector_store` | `BaseVectorStore` | `InMemoryVectorStore` | Vector storage backend |\n| `docstore` | `BaseDocstore` | `SimpleDocumentStore` | Document storage backend |\n| `index_store` | `BaseIndexStore` | `SimpleIndexStore` | Index metadata storage |\n| `graph_store` | `BaseGraphStore` | `None` | Knowledge graph storage |\n| `chat_store` | `BaseChatStore` | `SimpleChatStore` | Chat history storage |\n| `image_store` | `BaseImageStore` | `None` | Image storage backend |\n\n### Persistence Methods\n\n| Method | Description |\n|--------|-------------|\n| `persist(persist_dir, ...)` | Save all storage components to disk |\n| `from_defaults(**kwargs)` | Create context with default or specified settings |\n| `load_index_from_storage()` | Class method to load index from persisted storage |\n\n## Document Store\n\nThe document store manages the storage and retrieval of `BaseDocument` objects. LlamaIndex provides several document store implementations.\n\n### SimpleDocumentStore\n\nThe default in-memory document store backed by SQLite for persistence.\n\n```python\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\n\ndocstore = SimpleDocumentStore(\n persist_path=\"./docstore.json\",\n redis_host=\"localhost\",\n redis_port=6379,\n redis_password=None\n)\n```\n\n### Document Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_documents(documents, batch_size)` | Add documents to the store |\n| `get_document(doc_id)` | Retrieve a document by ID |\n| `delete(doc_id)` | Remove a document by ID |\n| `get_nodes(node_ids)` | Retrieve nodes by their IDs |\n| `get_all_nodes()` | Retrieve all nodes from the store |\n| `persist(persist_path)` | Persist the document store to disk |\n\n### Data Model\n\nDocuments are stored with the following structure:\n\n```python\nclass BaseDocument:\n id_: str # Unique identifier\n embedding: List[float] # Vector embedding\n metadata: Dict[str, Any] # User-defined metadata\n text: str # Document text content\n excluded_embed_metadata_keys: List[str]\n excluded_llm_metadata_keys: List[str]\n relationships: Dict[DocumentRelationship, str]\n hash: str # Computed hash for caching\n __class__: type # Document type (optional)\n```\n\n## Index Store\n\nThe index store manages index metadata and structure, enabling efficient retrieval of index components.\n\n### SimpleIndexStore\n\nThe default index store implementation using JSON file storage.\n\n```python\nfrom llama_index.core.storage.index_store import SimpleIndexStore\n\nindex_store = SimpleIndexStore(\n persist_path=\"./index_store.json\"\n)\n```\n\n### Index Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_index_struct(index_struct)` | Store an index structure |\n| `get_index_struct(struct_id)` | Retrieve index structure by ID |\n| `get_index_structs()` | List all stored index structures |\n| `delete_index_struct(struct_id)` | Remove an index structure |\n\n### Supported Index Types\n\n| Index Type | Description |\n|------------|-------------|\n| `VectorStoreIndex` | Dense vector-based retrieval |\n| `SummaryIndex` | Summary-based indexing |\n| `KeywordTableIndex` | Keyword-based retrieval |\n| `KnowledgeGraphIndex` | Graph-based knowledge indexing |\n\n## Chat Store\n\nThe chat store manages conversation history for multi-turn interactions with language models.\n\n### SimpleChatStore\n\nA persistent chat store implementation for storing and retrieving chat messages.\n\n```python\nfrom llama_index.core.storage.chat_store import SimpleChatStore\n\nchat_store = SimpleChatStore(\n persist_path=\"./chat_store.json\"\n)\n```\n\n### Chat Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_message(chat_id, message, role)` | Append a message to a chat session |\n| `get_messages(chat_id)` | Retrieve all messages for a chat |\n| `get_chat(chat_id)` | Get chat session details |\n| `delete_chat(chat_id)` | Remove a chat session |\n| `persist(persist_path)` | Save chat history to disk |\n\n### Message Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Message role (user/assistant/system) |\n| `content` | `str` | Message text content |\n| `additional_kwargs` | `Dict` | Extra metadata for the message |\n\n## Storage Workflow\n\n```mermaid\ngraph LR\n A[Create Documents] --> B[Initialize StorageContext]\n B --> C{Configure Backends}\n C --> D[In-Memory]\n C --> E[Persistent]\n D --> F[Build Index]\n E --> F\n F --> G[Index Created]\n G --> H[Persist to Disk]\n H --> I[StorageContext.persist]\n \n J[Load Index] --> K[load_index_from_storage]\n K --> L[Index Ready]\n```\n\n## Usage Examples\n\n### Basic Persistence\n\n```python\nfrom llama_index.core import VectorStoreIndex, StorageContext\n\n# Create documents\ndocuments = [...]\n\n# Create index with storage context\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\nindex = VectorStoreIndex.from_documents(\n documents, \n storage_context=storage_context\n)\n\n# Explicitly persist (optional - also happens on garbage collection)\nindex.storage_context.persist()\n```\n\n### Loading Persisted Index\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# Rebuild storage context from disk\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\n\n# Load existing index\nindex = load_index_from_storage(storage_context=storage_context)\n\n# Query the loaded index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"Your question here\")\n```\n\n### Custom Storage Configuration\n\n```python\nfrom llama_index.core import StorageContext\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\nfrom llama_index.core.storage.index_store import SimpleIndexStore\n\n# Create custom stores\ndocstore = SimpleDocumentStore(persist_path=\"./custom_docstore.json\")\nindex_store = SimpleIndexStore(persist_path=\"./custom_index_store.json\")\n\n# Configure storage context with custom stores\nstorage_context = StorageContext(\n docstore=docstore,\n index_store=index_store,\n persist_dir=\"./custom_storage\"\n)\n\n# Use with index\nindex = VectorStoreIndex.from_documents(\n documents,\n storage_context=storage_context\n)\n```\n\n## Storage Backend Comparison\n\n| Backend | Persistence | Performance | Scalability | Use Case |\n|---------|-------------|-------------|-------------|----------|\n| `SimpleDocumentStore` | JSON/SQLite | Medium | Low-Medium | Development, small datasets |\n| `RedisDocumentStore` | Redis | High | High | Production, distributed systems |\n| `MongoDocumentStore` | MongoDB | High | Very High | Large-scale deployments |\n| `KVDocumentStore` | Key-Value | High | Medium-High | General purpose |\n\n## Best Practices\n\n1. **Always specify unique document IDs**: Prevents duplicate entries and enables predictable retrieval\n ```python\n Document(id_=\"unique_doc_1\", text=\"content\")\n ```\n\n2. **Configure persistence early**: Set up storage context before building indexes to avoid data loss\n\n3. **Use appropriate batch sizes**: When adding many documents, use batch operations for better performance\n\n4. **Handle persistence errors**: Wrap persistence calls in try-except blocks for robustness\n\n5. **Backup important data**: Regularly backup persisted storage directories\n\n## Related Components\n\n- **Vector Stores**: Manage embedding vectors for semantic search\n- **Graph Stores**: Handle knowledge graph data structures\n- **Image Stores**: Store image data for multimodal applications\n- **Query Engines**: Use storage to retrieve relevant documents for queries\n- **Retrievers**: Access stored data for retrieval-augmented generation\n\n---\n\n\n\n## Query Engines\n\n### 相关页面\n\n相关主题：[Retrieval and Reranking](#retrieval-reranking), [Documents and Nodes](#documents-nodes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/query_engine/sub_question_query_engine.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/sub_question_query_engine.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- [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/query_engine/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/__init__.py)\n \n\n# Query Engines\n\nQuery Engines are the core components in LlamaIndex responsible for processing user queries and returning relevant responses by retrieving, synthesizing, and formatting information from indexed data.\n\n## Overview\n\nQuery Engines serve as the primary interface for querying indexed documents in LlamaIndex. They coordinate the retrieval of relevant context from the index and synthesize this information into coherent, helpful responses using Large Language Models (LLMs).\n\n**Key Responsibilities:**\n\n- Receive user queries and transform them into retrieval operations\n- Coordinate with retrievers to fetch relevant documents or data chunks\n- Route queries to appropriate response synthesizers\n- Handle query-time configuration such as similarity thresholds and response modes\n\n资料来源：[llama-index-core/llama_index/core/query_engine/__init__.py]()\n\n## Architecture\n\nThe query engine architecture follows a modular pipeline pattern where different components handle specific stages of query processing.\n\n```mermaid\ngraph TD\n A[User Query] --> B[Query Engine]\n B --> C[Retriever]\n C --> D[Node Postprocessor]\n D --> E[Response Synthesizer]\n E --> F[LLM]\n F --> G[Response]\n \n H[Vector Store Index] --> C\n I[Summary Index] --> C\n J[Knowledge Graph Index] --> C\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| BaseQueryEngine | Abstract base class defining the query interface | `llama_index.core.query_engine` |\n| RetrieverQueryEngine | Default query engine using retrievers | `retriever_query_engine.py` |\n| SubQuestionQueryEngine | Decomposes complex queries into sub-questions | `sub_question_query_engine.py` |\n| ResponseSynthesizer | Generates responses from retrieved context | `llama_index.core.response_synthesizers` |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py]()\n\n## RetrieverQueryEngine\n\nThe `RetrieverQueryEngine` is the default query engine implementation that combines retrieval with response synthesis.\n\n### Initialization\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\nindex = VectorStoreIndex.from_documents(documents)\nquery_engine = index.as_query_engine()\n```\n\n### Constructor Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| retriever | BaseRetriever | Required | The retriever used to fetch relevant nodes |\n| response_synthesizer | BaseSynthesizer | None | Synthesizer for generating responses |\n| node_postprocessors | List[BaseNodePostprocessor] | [] | Post-processors applied after retrieval |\n| callback_manager | CallbackManager | None | Manages callbacks for query events |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py:40-60]()\n\n### Query Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant QueryEngine\n participant Retriever\n participant Postprocessor\n participant Synthesizer\n participant LLM\n \n User->>QueryEngine: query(question)\n QueryEngine->>Retriever: retrieve(query_str)\n Retriever-->>QueryEngine: nodes[]\n QueryEngine->>Postprocessor: postprocess(nodes)\n Postprocessor-->>QueryEngine: filtered_nodes[]\n QueryEngine->>Synthesizer: synthesize(query_str, nodes)\n Synthesizer->>LLM: generate(prompt)\n LLM-->>Synthesizer: response\n Synthesizer-->>QueryEngine: Response\n QueryEngine-->>User: Response\n```\n\n## SubQuestionQueryEngine\n\nThe `SubQuestionQueryEngine` handles complex queries by decomposing them into simpler sub-questions that can be answered independently.\n\n### Use Cases\n\n- Queries requiring information from multiple data sources\n- Complex questions that benefit from step-by-step reasoning\n- Multi-hop questions requiring logical deduction\n\n### Configuration\n\n```python\nfrom llama_index.core.query_engine import SubQuestionQueryEngine\nfrom llama_index.core.callbacks import CallbackManager\n\nquery_engine = SubQuestionQueryEngine.from_defaults(\n query_engine_tools=query_engine_tools,\n callback_manager=CallbackManager([callback]),\n verbose=True\n)\n```\n\n### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| query_engine_tools | List[QueryEngineTool] | Required | List of query engines and their descriptions |\n| response_synthesizer | BaseSynthesizer | None | Response synthesizer to use |\n| sub_question_name | str | \"sub_question\" | Name for sub-question events |\n| parent_name | str | \"parent_question\" | Name for parent question events |\n| callback_manager | CallbackManager | None | Callback manager for events |\n| verbose | bool | False | Enable verbose output |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py:50-80]()\n\n## Response Synthesizers\n\nResponse Synthesizers transform retrieved context into natural language responses.\n\n### Available Synthesizer Types\n\n| Synthesizer | Description | Use Case |\n|-------------|-------------|----------|\n| CompactAndRefine | Compacts retrieved context before generating | Large retrieval results |\n| TreeSummarize | Hierarchically summarizes retrieved nodes | Comprehensive responses |\n| SimpleSummarize | Direct concatenation and summarization | Quick, simple responses |\n| Refine | Iteratively improves response quality | High-quality refinement |\n| Accumulate | Combines responses from multiple sources | Multi-source queries |\n| Generation | Direct LLM generation from context | Simple generation tasks |\n\n### Base Interface\n\n```python\nclass BaseSynthesizer(ABC):\n @abstractmethod\n async def synthesize(\n self,\n query: QueryBundle,\n nodes: List[NodeWithScore],\n **kwargs: Any\n ) -> Response:\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/response_synthesizers/base.py:30-50]()\n\n## Vector Store Index Query Engine\n\nThe `VectorStoreIndex` provides built-in query engine creation through the `as_query_engine()` method.\n\n### Factory Method Parameters\n\n```python\nindex.as_query_engine(\n query_mode: str = \"default\",\n similarity_top_k: int = 10,\n vector_store_query_mode: str = \"default\",\n alpha: Optional[float] = None,\n **kwargs: Any\n) -> BaseQueryEngine\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| query_mode | str | \"default\" | Query execution mode |\n| similarity_top_k | int | 10 | Number of top results to retrieve |\n| vector_store_query_mode | str | \"default\" | Vector store specific query mode |\n| alpha | float | None | Hybrid search weight (0-1, default 0.5) |\n\n资料来源：[llama-index-core/llama_index/core/indices/vector_store/base.py]()\n\n### Query Modes\n\n| Mode | Description |\n|------|-------------|\n| `default` | Standard retrieval based on similarity |\n| `mmr` | Maximum Marginal Relevance for diverse results |\n| `hybrid` | Combines sparse and dense retrieval |\n\n## Query Engine Tool\n\nFor agent-based workflows, query engines can be wrapped as tools using the `QueryEngineTool` class.\n\n```python\nfrom llama_index.core.tools import QueryEngineTool\n\ntool = QueryEngineTool(\n query_engine=query_engine,\n metadata=ToolMetadata(\n name=\"website_index\",\n description=\"Useful for answering questions about text on websites\",\n )\n)\n```\n\n资料来源：[llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py:100-120]()\n\n## Advanced Configuration\n\n### Node Post-processors\n\nPost-processors filter and enhance retrieved nodes before synthesis.\n\n```python\nfrom llama_index.core.postprocessor import SimilarityPostprocessor\n\nquery_engine = index.as_query_engine(\n node_postprocessors=[\n SimilarityPostprocessor(similarity_cutoff=0.7)\n ]\n)\n```\n\n### Custom Query Engines\n\nCreate custom query engines by extending the base class:\n\n```python\nfrom llama_index.core.query_engine import BaseQueryEngine\n\nclass CustomQueryEngine(BaseQueryEngine):\n def __init__(self, retriever, synthesizer):\n self._retriever = retriever\n self._synthesizer = synthesizer\n \n async def _aquery(self, query_bundle: QueryBundle) -> Response:\n nodes = await self._retriever.aretrieve(query_bundle)\n response = await self._synthesizer.synthesize(\n query_bundle, nodes\n )\n return response\n```\n\n## Async Query Execution\n\nQuery engines support both sync and async execution patterns:\n\n```python\n# Synchronous\nresponse = query_engine.query(\"What is LlamaIndex?\")\n\n# Asynchronous\nresponse = await query_engine.aquery(\"What is LlamaIndex?\")\n```\n\n## Integration with Vector Indices\n\nQuery engines integrate with various index types:\n\n| Index Type | Default Query Engine | Features |\n|------------|---------------------|----------|\n| VectorStoreIndex | RetrieverQueryEngine | Semantic similarity search |\n| SummaryIndex | RetrieverQueryEngine | Full document retrieval |\n| KnowledgeGraphIndex | RetrieverQueryEngine | Graph-based traversal |\n| ComposableGraph | SubQuestionQueryEngine | Multi-index queries |\n\n## Best Practices\n\n1. **Choose appropriate top_k**: Balance between response quality and speed (typically 3-10 for most use cases)\n\n2. **Use sub-question engine for complex queries**: When queries require reasoning across multiple sources\n\n3. **Configure similarity thresholds**: Filter low-quality matches using post-processors\n\n4. **Enable callbacks for debugging**: Monitor query execution flow and performance\n\n5. **Select appropriate synthesizers**: Match the synthesizer type to your response quality requirements\n\n## Summary\n\nQuery Engines in LlamaIndex provide a flexible, extensible framework for retrieving and synthesizing information from indexed data. The modular architecture allows for customization at every stage of the query pipeline, from retrieval configuration to response generation.\n\n**Key Takeaways:**\n\n- Query engines orchestrate the retrieval-synthesis pipeline\n- `RetrieverQueryEngine` handles standard query flows\n- `SubQuestionQueryEngine` decomposes complex queries\n- Response synthesizers generate final output from context\n- Extensive configuration options enable fine-tuned control\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/response_synthesizers/base.py]()\n资料来源：[llama-index-core/llama_index/core/indices/vector_store/base.py]()\n\n---\n\n\n\n## Retrieval and Reranking\n\n### 相关页面\n\n相关主题：[Query Engines](#query-engines), [Storage Systems](#storage-systems)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/retrievers/recursive_retriever.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/retrievers/recursive_retriever.py)\n- [llama-index-core/llama_index/core/postprocessor/llm_rerank.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/llm_rerank.py)\n- [llama-index-core/llama_index/core/postprocessor/node.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/node.py)\n- [llama-index-core/llama_index/core/indices/property_graph/retriever.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/property_graph/retriever.py)\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/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md)\n \n\n# Retrieval and Reranking\n\n## Overview\n\nRetrieval and Reranking are fundamental components in LlamaIndex's architecture for building effective Retrieval-Augmented Generation (RAG) systems. The retrieval system identifies relevant context from various data sources, while the reranking system reorders retrieved results to optimize relevance using advanced techniques like LLM-based scoring.\n\nIn LlamaIndex, retrieval is handled through a flexible retriever abstraction that supports multiple retrieval strategies including vector-based search, keyword search, and hybrid approaches. Reranking serves as a post-processing step that improves result quality by reordering retrieved nodes based on more sophisticated relevance criteria.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Retrieval Phase]\n B --> C[Vector/Knowledge Graph Retrieval]\n C --> D[Initial Node Set]\n D --> E[Reranking Phase]\n E --> F[LLM Reranker]\n F --> G[Reordered Results]\n G --> H[Response Generation]\n \n I[Document Sources] --> J[Indexing]\n J --> K[Vector Store / Graph Store]\n K --> C\n```\n\n## Retrieval Components\n\n### Retriever Abstraction\n\nLlamaIndex provides a base `BaseRetriever` class that defines the interface for all retrieval implementations. Retrievers work in conjunction with indices to fetch relevant nodes from vector stores or knowledge graphs.\n\n**Core Retriever Classes:**\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| `BaseRetriever` | `llama-index-core/llama_index/core/retrievers/` | Abstract base for all retrievers |\n| `RecursiveRetriever` | `llama-index-core/llama_index/core/retrievers/recursive_retriever.py` | Multi-level recursive retrieval |\n| `PropertyGraphRetriever` | `llama-index-core/llama_index/core/indices/property_graph/retriever.py` | Graph-based retrieval |\n\n### Recursive Retriever\n\nThe `RecursiveRetriever` enables multi-level, hierarchical retrieval across different data sources and node types. It supports recursive traversal of indices and can fetch related nodes across different retrieval strategies.\n\n**Key Features:**\n- Recursive node resolution across index hierarchies\n- Support for multiple retriever types in a chain\n- Handling of nested document structures\n\n**Source:** `llama-index-core/llama_index/core/retrievers/recursive_retriever.py`\n\n### Property Graph Retriever\n\nThe Property Graph Retriever leverages knowledge graphs for retrieval, enabling structured queries over entity-relationship data. This retriever is particularly effective for complex queries requiring relationship-aware context.\n\n**Capabilities:**\n- Graph traversal-based retrieval\n- Entity filtering and relationship queries\n- Support for hybrid graph + vector search\n\n**Source:** `llama-index-core/llama_index/core/indices/property_graph/retriever.py:1-100`\n\n## Reranking System\n\n### Purpose and Role\n\nReranking improves retrieval quality by reordering initially retrieved candidates using more sophisticated relevance models. After an initial retrieval pass identifies candidate nodes, rerankers evaluate and reorder these results to maximize relevance to the query.\n\n### LLM Reranker\n\nThe `LLMRerank` post-processor uses a Language Model to score and reorder retrieved nodes based on semantic relevance. This approach provides higher quality ranking compared to simple vector similarity.\n\n**Key Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `top_n` | `int` | `None` | Number of top results to return after reranking |\n| `choice_batch_size` | `int` | `10` | Batch size for LLM ranking choices |\n| `llm` | `BaseLLM` | `None` | Language model for scoring |\n| `verbose` | `bool` | `False` | Enable verbose output |\n\n**Source:** `llama-index-core/llama_index/core/postprocessor/llm_rerank.py`\n\n### Node Post-Processors\n\nThe `NodePostprocessor` class provides additional filtering and transformation capabilities for retrieved nodes. These processors operate on the node level and can apply various transformations before final output.\n\n**Common Post-Processing Operations:**\n- Duplicate removal\n- Similarity threshold filtering\n- Metadata-based filtering\n\n**Source:** `llama-index-core/llama_index/core/postprocessor/node.py`\n\n## Data Flow\n\n```mermaid\ngraph LR\n A[User Query] --> B[Vector Search]\n B --> C[Top-K Nodes]\n C --> D[Post-Processors]\n D --> E[LLM Reranker]\n E --> F[Reranked Nodes]\n F --> G[Context for LLM]\n \n H[Documents] --> I[Indexing Pipeline]\n I --> J[Embedding Model]\n J --> K[Vector Store]\n K --> B\n```\n\n## Integration with Data Loaders\n\nLlamaIndex's retrieval system integrates seamlessly with various data loaders that prepare documents for indexing and retrieval.\n\n### Supported Data Sources\n\n| Reader | Use Case | Integration |\n|--------|----------|-------------|\n| `DoclingReader` | PDF, DOCX, HTML | `llama-index-readers-docling` |\n| `SimpleWebPageReader` | Static websites | `llama-index-readers-web` |\n| `RemoteDepthReader` | Multi-level URL crawling | `llama-index-readers-remote-depth` |\n| `WikipediaReader` | Wikipedia articles | `llama-index-readers-wikipedia` |\n| `SemanticScholarReader` | Academic papers | `llama-index-readers-semanticscholar` |\n\n**Source:** `llama-index-integrations/readers/llama-index-readers-docling/README.md`\n\n### Document Processing Pipeline\n\nDocuments loaded through readers undergo the following processing:\n\n1. **Parsing** - Extract text content from various formats (PDF, DOCX, HTML)\n2. **Node Parsing** - Split documents into semantic chunks (nodes)\n3. **Embedding** - Generate vector embeddings for each node\n4. **Indexing** - Store nodes and embeddings in appropriate stores\n5. **Retrieval** - Fetch relevant nodes based on queries\n\n**Source:** `llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md`\n\n## Usage Patterns\n\n### Basic Retrieval with Reranking\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.core.postprocessor import LLMRerank\n\n# Load documents and create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Configure reranking\nreranker = LLMRerank(\n top_n=5,\n choice_batch_size=10\n)\n\n# Query with reranking\nquery_engine = index.as_query_engine(\n node_postprocessors=[reranker]\n)\n\nresponse = query_engine.query(\"Your question here\")\n```\n\n### Recursive Retrieval\n\n```python\nfrom llama_index.core.retrievers import RecursiveRetriever\n\n# Configure recursive retrieval across multiple levels\nrecursive_retriever = RecursiveRetriever(\n retriever_dict={\n \"root\": vector_retriever,\n \"documents\": document_retriever\n }\n)\n```\n\n## Configuration Options\n\n### Retrieval Configuration\n\n| Option | Description | Applies To |\n|--------|-------------|------------|\n| `similarity_top_k` | Number of initial candidates | Vector retrieval |\n| `retrieval_mode` | Vector, keyword, or hybrid | Hybrid search |\n| `node_postprocessors` | List of post-processing steps | All retrievers |\n\n### Reranking Configuration\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `top_n` | Final number of results | 5 |\n| `score_threshold` | Minimum relevance score | None |\n| `model` | Reranking model | gpt-3.5-turbo |\n\n## Advanced Topics\n\n### Hybrid Retrieval with Reranking\n\nCombining vector and keyword search with LLM reranking provides robust retrieval across diverse query types:\n\n1. **Vector Search** - Captures semantic similarity\n2. **Keyword Search** - Captures exact term matching\n3. **LLM Reranking** - Optimizes final ordering\n\n### Custom Retrievers\n\nDevelopers can create custom retrievers by extending `BaseRetriever`:\n\n```python\nfrom llama_index.core.retrievers import BaseRetriever\n\nclass CustomRetriever(BaseRetriever):\n def _retrieve(self, query_bundle):\n # Custom retrieval logic\n pass\n```\n\n## Summary\n\nRetrieval and Reranking in LlamaIndex form a two-phase system where initial retrieval identifies candidate nodes and reranking optimizes their ordering. The architecture supports multiple retrieval strategies (vector, graph, recursive) and leverages LLM-based reranking for improved result quality. Integration with various data loaders enables seamless indexing from diverse sources, while the post-processor abstraction allows flexible pipeline customization.\n\n---\n\n\n\n## Agent Framework\n\n### 相关页面\n\n相关主题：[Memory Systems](#memory-systems)\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# Agent Framework\n\n## Overview\n\nThe LlamaIndex Agent Framework provides a flexible, extensible system for building AI agents that can reason, plan, and execute actions using tools. The framework enables the creation of both single-agent and multi-agent systems capable of interacting with external data sources, performing complex reasoning tasks, and orchestrating workflows.\n\nAgents in LlamaIndex are designed to combine large language model (LLM) capabilities with structured tool usage, memory management, and workflow orchestration. The framework supports various agent types including ReAct (Reasoning + Acting) agents and workflow-based agents.\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:1-50]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User Query] --> B[Agent]\n B --> C[Reasoning Engine]\n C --> D[Tool System]\n D --> E[External Tools]\n C --> F[Memory]\n B --> G[Workflow Orchestrator]\n G --> H[Sub-Agents]\n H --> D\n```\n\nThe framework is built on several key components that work together to enable sophisticated agent behaviors:\n\n| Component | Purpose |\n|-----------|---------|\n| **Agent** | Core entity that processes queries and generates responses |\n| **Reasoning Engine** | Handles thought processes and decision making |\n| **Tool System** | Provides access to external functions and APIs |\n| **Memory** | Stores conversation history and intermediate results |\n| **Workflow Orchestrator** | Manages complex multi-step tasks |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:50-100]()\n\n## ReAct Agent\n\nThe ReAct (Synergizing Reasoning and Acting) agent implements a reasoning loop that combines thought processes with tool actions. This agent type is particularly effective for tasks requiring logical deduction and external information retrieval.\n\n### ReAct Formatter\n\nThe ReAct formatter is responsible for constructing prompts that guide the agent through the reasoning-action-observation cycle. It defines the structure of thoughts, actions, and observations in the agent's prompt.\n\n```mermaid\ngraph LR\n A[Thought] --> B[Action]\n B --> C[Observation]\n C --> A\n```\n\n#### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| `system_prompt` | Instructions for the agent's role and behavior |\n| `tool_prompt` | Description of available tools |\n| `formatter` | Defines the format for thoughts, actions, observations |\n| `examples` | Few-shot examples for better performance |\n\n资料来源：[llama-index-core/llama_index/core/agent/react/formatter.py:1-80]()\n\n### ReAct Output Parsing\n\nThe ReAct agent uses specialized output parsers to extract structured information from LLM responses:\n\n```python\nclass ReActOutputParser:\n def parse(self, output: str) -> ActionOutput:\n # Parse thought, action, and action input from output\n pass\n```\n\nThis parsing enables the agent to:\n1. Extract the reasoning thought process\n2. Identify the tool to invoke\n3. Extract the tool's input parameters\n4. Process the tool's output as an observation\n\n资料来源：[llama-index-core/llama_index/core/agent/react/formatter.py:80-150]()\n\n## Workflow-Based Agents\n\nWorkflow-based agents provide a more structured approach to agent execution, using state machines and defined steps to process queries.\n\n### Base Agent\n\nThe `BaseAgent` class provides the foundation for all agent implementations in the workflow system:\n\n```mermaid\ngraph TD\n A[Input] --> B[State Machine]\n B --> C{Step Execution}\n C -->|Step 1| D[Process Step]\n D --> E[Update State]\n E --> C\n C -->|Complete| F[Generate Response]\n```\n\n#### Base Agent API\n\n| Method | Description |\n|--------|-------------|\n| `run()` | Execute the agent with input |\n| `reset()` | Reset agent state |\n| `get_state()` | Retrieve current agent state |\n| `set_state()` | Set agent state |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:100-200]()\n\n### Agent State Management\n\nAgents maintain state throughout their execution, which includes:\n\n| State Component | Type | Purpose |\n|-----------------|------|---------|\n| `input` | str | Original user input |\n| `current_step` | int | Current execution step |\n| `memory` | Memory | Conversation history |\n| `context` | dict | Additional context data |\n| `steps` | List[Step] | Executed steps |\n| `output` | Any | Final output |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:200-300]()\n\n## Tool System\n\nThe Tool System enables agents to interact with external resources and perform actions beyond text generation.\n\n### Function Tool\n\n`FunctionTool` provides a decorator-based interface for creating tools from Python functions:\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\n@FunctionTool.from_defaults\ndef search_database(query: str) -> str:\n \"\"\"Search the knowledge base for relevant information.\"\"\"\n # Implementation here\n return results\n```\n\n#### FunctionTool Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `fn` | Callable | Required | The function to wrap |\n| `name` | str | Function name | Tool identifier |\n| `description` | str | Function docstring | Tool description for LLM |\n| `fn_schema` | BaseModel | Auto-generated | Input schema |\n| `return_direct` | bool | False | Return raw output |\n\n资料来源：[llama-index-core/llama_index/core/tools/function_tool.py:1-100]()\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ToolRegistry\n participant FunctionTool\n participant External\n\n Agent->>ToolRegistry: Request tool by name\n ToolRegistry->>FunctionTool: Get tool instance\n FunctionTool->>External: Execute function\n External-->>FunctionTool: Return result\n FunctionTool-->>Agent: Format response\n```\n\n### Creating Custom Tools\n\nTools can be created using the `@FunctionTool.from_defaults` decorator:\n\n```python\n@FunctionTool.from_defaults(name=\"calculator\", description=\"Perform mathematical calculations\")\ndef calculate(expression: str) -> str:\n \"\"\"Evaluate a mathematical expression.\"\"\"\n return str(eval(expression))\n```\n\nOr programmatically:\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\ndef my_function(arg1: str, arg2: int) -> str:\n return f\"{arg1} repeated {arg2} times\"\n\ntool = FunctionTool.from_defaults(\n fn=my_function,\n name=\"my_tool\",\n description=\"Custom tool description\"\n)\n```\n\n资料来源：[llama-index-core/llama_index/core/tools/function_tool.py:100-200]()\n\n## Multi-Agent Workflows\n\nMulti-agent systems enable complex task decomposition where different specialized agents collaborate to solve problems.\n\n### Multi-Agent Workflow Architecture\n\n```mermaid\ngraph TD\n A[Coordinator Agent] --> B[Specialist Agent 1]\n A --> C[Specialist Agent 2]\n A --> D[Specialist Agent N]\n B --> E[Tool 1]\n C --> F[Tool 2]\n D --> G[Tool N]\n B --> A\n C --> A\n D --> A\n```\n\n### Workflow Communication\n\nAgents communicate through a shared state and message-passing mechanism:\n\n| Message Type | Direction | Purpose |\n|--------------|-----------|---------|\n| `task` | Coordinator → Specialist | Assign task |\n| `result` | Specialist → Coordinator | Return results |\n| `query` | Any → Any | Request information |\n| `response` | Any → Any | Provide information |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:1-100]()\n\n### Creating Multi-Agent Systems\n\n```python\nfrom llama_index.core.agent.workflow import MultiAgentWorkflow\n\n# Create specialized agents\nresearch_agent = ReActAgent.from_tools(tools=[search_tool], name=\"researcher\")\nanalysis_agent = ReActAgent.from_tools(tools=[analysis_tool], name=\"analyst\")\n\n# Create multi-agent workflow\nworkflow = MultiAgentWorkflow(agents=[research_agent, analysis_agent])\n\n# Execute workflow\nresult = workflow.run(user_input=\"Analyze the latest research on AI\")\n```\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:100-200]()\n\n## Tool Integration with LlamaIndex Readers\n\nThe Agent Framework integrates seamlessly with LlamaIndex's document readers, enabling agents to query and reason over loaded documents:\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.core.agent import ReActAgent\n\n# Load documents\ndocuments = SimpleDirectoryReader(\"./data\").load_data()\nindex = VectorStoreIndex.from_documents(documents)\n\n# Create query engine tool\nquery_tool = index.as_query_engine()\n\n# Create agent with query tool\nagent = ReActAgent.from_tools(tools=[query_tool])\nresponse = agent.chat(\"What is the main topic of these documents?\")\n```\n\nThis integration allows agents to:\n- Query vector databases\n- Retrieve relevant context\n- Synthesize information from multiple sources\n- Perform RAG (Retrieval-Augmented Generation)\n\n## Best Practices\n\n### Designing Effective Tools\n\n| Guideline | Rationale |\n|-----------|-----------|\n| Clear descriptions | Helps LLM understand when to use the tool |\n| Structured outputs | Easier for agent to parse and use results |\n| Error handling | Prevents agent crashes from tool failures |\n| Idempotent operations | Enables safe retries |\n\n### Agent Configuration\n\n| Parameter | Recommendation |\n|-----------|----------------|\n| `max_iterations` | Set based on task complexity (default: 10) |\n| `timeout` | Allow sufficient time for tool execution |\n| `memory_type` | Use conversation memory for multi-turn interactions |\n| `tool_retriever` | Implement for large tool collections |\n\n### Debugging Agents\n\n1. **Enable verbose mode** to see agent's reasoning traces\n2. **Log tool inputs/outputs** to verify correct tool usage\n3. **Test tools independently** before combining with agent\n4. **Monitor token usage** to prevent excessive spending\n\n## See Also\n\n- [ReAct Agent Documentation](https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/)\n- [Workflow Documentation](https://docs.llamaindex.ai/en/stable/module_guides/deploying/workflow/)\n- [Tool System](https://docs.llamaindex.ai/en/stable/module_guides/deploying/tools/)\n- [LlamaIndex Core](https://github.com/run-llama/llama_index/tree/main/llama-index-core)\n\n---\n\n\n\n## Memory Systems\n\n### 相关页面\n\n相关主题：[Agent Framework](#agent-framework), [Storage Systems](#storage-systems)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/memory/chat_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_memory_buffer.py)\n- [llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py)\n- [llama-index-core/llama_index/core/memory/vector_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/vector_memory.py)\n- [llama-index-core/llama_index/core/memory/simple_composable_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/simple_composable_memory.py)\n- [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n \n\n# Memory Systems\n\nMemory Systems in LlamaIndex provide persistent conversation history management for chat engines and agents. They enable AI applications to maintain context across multiple interactions, store user preferences, and retrieve relevant historical information during conversations.\n\n## Architecture Overview\n\nMemory Systems follow a modular architecture that allows different memory implementations to be composed and used interchangeably. The core memory system supports multiple storage strategies including buffer-based, summary-based, and vector-based retrieval.\n\n```mermaid\ngraph TD\n A[Chat Engine / Agent] --> B[Memory System]\n B --> C[ChatMemoryBuffer]\n B --> D[ChatSummaryMemoryBuffer]\n B --> E[VectorMemory]\n B --> F[Mem0Memory]\n C --> G[SimpleComposableMemory]\n D --> G\n E --> G\n F --> H[External Memory Services]\n \n G --> I[Storage Backend]\n H --> J[Mem0 Platform API]\n```\n\n## Core Memory Components\n\n### ChatMemoryBuffer\n\n`ChatMemoryBuffer` is the foundational memory component that stores conversation history in a simple buffer structure. It maintains a list of chat messages and provides methods for adding, retrieving, and managing conversation context.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `chat_history` | `List[ChatMessage]` | List of conversation messages |\n| `size` | `int` | Maximum number of messages to retain |\n| `tokenizer` | `Callable` | Function to count tokens |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/chat_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_memory_buffer.py)\n\n### ChatSummaryMemoryBuffer\n\n`ChatSummaryMemoryBuffer` extends the basic buffer with summarization capabilities. When the conversation exceeds the configured size, older messages are condensed into a summary rather than being discarded entirely.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `llm` | `LLM` | LLM instance for generating summaries |\n| `chat_history` | `List[ChatMessage]` | Initial conversation history |\n| `size` | `int` | Maximum buffer size before summarization |\n| `summary_exists` | `bool` | Flag indicating if summary is generated |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py)\n\n### VectorMemory\n\n`VectorMemory` uses vector embeddings to store and retrieve conversation history. This enables semantic search within the conversation history, allowing the system to find relevant past messages based on meaning rather than exact matches.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `vector_store` | `VectorStore` | Storage backend for embeddings |\n| `embed_model` | `EmbeddingModel` | Model for generating embeddings |\n| `index` | `VectorStoreIndex` | Index for efficient retrieval |\n| `retriever` | `BaseRetriever` | Retrieval mechanism |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/vector_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/vector_memory.py)\n\n### SimpleComposableMemory\n\n`SimpleComposableMemory` provides a framework for combining multiple memory types into a unified interface. This allows different memory strategies to work together, leveraging the strengths of each approach.\n\n| Feature | Description |\n|---------|-------------|\n| Memory Composition | Combine buffer, summary, and vector memories |\n| Unified Interface | Single API for all memory operations |\n| Flexible Retrieval | Query multiple memory sources simultaneously |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/simple_composable_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/simple_composable_memory.py)\n\n## Mem0 Memory Integration\n\nThe `Mem0Memory` integration provides access to the Mem0 Platform for advanced memory management. Mem0 offers enhanced capabilities for semantic memory storage, user preference tracking, and cross-session persistence.\n\n### Configuration Options\n\n#### Client-Based Initialization\n\n```python\nfrom llama_index.memory.mem0 import Mem0Memory\n\ncontext = {\"user_id\": \"user_1\"}\nmemory = Mem0Memory.from_client(\n context=context,\n api_key=\"\",\n search_msg_limit=4,\n)\n```\n\n#### Config Dictionary Initialization\n\n```python\nmemory = Mem0Memory.from_config(\n context=context,\n config={\n \"provider\": \"openai\",\n \"config\": {\"model\": \"text-embedding-3-small\"},\n \"version\": \"v1.1\",\n },\n search_msg_limit=4,\n)\n```\n\n### Context Parameters\n\nThe Mem0 context identifies the entity for which memory is stored:\n\n| Parameter | Description |\n|-----------|-------------|\n| `user_id` | Unique identifier for the user |\n| `agent_id` | Unique identifier for the agent |\n| `run_id` | Unique identifier for the conversation run |\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Usage Patterns\n\n### Integration with SimpleChatEngine\n\n```python\nfrom llama_index.core import SimpleChatEngine\nfrom llama_index.memory.mem0 import Mem0Memory\n\nmemory = Mem0Memory.from_client(\n context={\"user_id\": \"user_1\"},\n api_key=\"\",\n)\n\nchat_engine = SimpleChatEngine.from_defaults(\n llm=llm,\n memory=memory\n)\n\nresponse = chat_engine.chat(\"Hi, My name is Mayank\")\n```\n\n### Integration with FunctionAgent\n\n```python\nfrom llama_index.core.tools import FunctionTool\nfrom llama_index.memory.mem0 import Mem0Memory\n\nmemory = Mem0Memory.from_client(\n context={\"user_id\": \"user_1\"},\n api_key=\"\",\n)\n\n# Use memory with agent for persistent context\nagent = FunctionAgent(\n llm=llm,\n tools=[call_tool, email_tool],\n memory=memory\n)\n```\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Memory Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant ChatEngine\n participant Memory\n participant Storage\n \n User->>ChatEngine: Send message\n ChatEngine->>Memory: Get context (search_msg_limit messages)\n Memory->>Storage: Query recent messages\n Storage-->>Memory: Return relevant messages\n Memory-->>ChatEngine: Context messages\n ChatEngine->>ChatEngine: Generate response\n ChatEngine->>Memory: Store new message\n Memory->>Storage: Persist message\n ChatEngine-->>User: Return response\n```\n\n## Comparison of Memory Types\n\n| Memory Type | Storage Method | Use Case | Scalability |\n|-------------|----------------|----------|-------------|\n| ChatMemoryBuffer | List/Buffer | Short conversations | Limited by token size |\n| ChatSummaryMemoryBuffer | Condensed summaries | Long conversations | Better for extended chats |\n| VectorMemory | Embeddings | Semantic search | Scales with vector store |\n| Mem0Memory | External API | Production applications | Cloud-native scaling |\n\n## Environment Configuration\n\nFor Mem0 integration, set the API key as an environment variable:\n\n```bash\nexport MEM0_API_KEY=\"\"\n```\n\nFor LLM integration within memory operations:\n\n```bash\nexport OPENAI_API_KEY=\"\"\n```\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Best Practices\n\n1. **Choose Appropriate Memory Type**: Select based on conversation length and retrieval needs\n2. **Configure Token Limits**: Set appropriate `search_msg_limit` to balance context and performance\n3. **Use Context Parameters**: Always provide user_id, agent_id, or run_id for proper memory isolation\n4. **Consider Composability**: Use `SimpleComposableMemory` for complex memory requirements\n5. **Monitor API Costs**: When using Mem0, track API usage for cost optimization\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：run-llama/llama_index\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo: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 项目说明书",
"目录",
"Introduction to LlamaIndex",
"Overview",
"Core Architecture",
"Core modules (included in llama-index-core)",
"Integration modules (from separate packages)",
"Concrete examples",
"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": "23bd65aaf79ffed587af35f325738b1580b35dea",
"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- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 llama-index 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install llama-index-core` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install llama-index-llms-openai` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install llama-index-llms-ollama` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install llama-index-embeddings-huggingface` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install llama-index-readers-github[github-app]` 证据：`llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md` Claim：`clm_0007` unverified 0.25\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `llama-index-integrations/readers/llama-index-readers-github/GITHUB_APP_QUICKSTART.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：9270\n- 重要文件覆盖：40/9270\n- 证据索引条目：80\n- 角色 / Skill 条目：80\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 llama-index 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 llama-index 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 llama-index 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 80 个角色 / Skill / 项目文档条目。\n\n- **Building Retrieval Augmented Generation RAG Applications with LlamaIndex**（project_doc）：Building Retrieval Augmented Generation RAG Applications with LlamaIndex 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples/cookbooks/oreilly_course_cookbooks/README.md`\n- **define sample Tool**（project_doc）：Putting together an agent in LlamaIndex can be done by defining a set of tools and providing them to our ReActAgent or FunctionAgent implementation. We're using it here with OpenAI, but it can be used with any sufficiently capable LLM. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/content/docs/framework/understanding/putting_it_all_together/agents.md`\n- **Use Cases**（project_doc）：An \"agent\" is an automated reasoning and decision engine. It takes in a user input/query and can make internal decisions for executing that query in order to return the correct result. The key agent components can include, but are not limited to: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/content/docs/framework/use_cases/agents.md`\n- **Google Doc Loader**（project_doc）：pip install llama-index-readers-google 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/readers/llama-index-readers-google/llama_index/readers/google/docs/README.md`\n- **🎯 Quick Start Guide**（project_doc）：Welcome to LlamaIndex ! We’re excited that you want to contribute and become part of our growing community. Whether you're interested in building integrations, fixing bugs, or adding exciting new features, we've made it easy for you to get started. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/content/docs/framework/CONTRIBUTING.md`\n- **🗂️ LlamaIndex 🦙**（project_doc）：! PyPI - Downloads https://img.shields.io/pypi/dm/llama-index https://pypi.org/project/llama-index/ ! Build https://github.com/run-llama/llama index/actions/workflows/build package.yml/badge.svg https://github.com/run-llama/llama index/actions/workflows/build package.yml ! GitHub contributors https://img.shields.io/github/contributors/jerryjliu/llama index https://github.com/jerryjliu/llama index/graphs/contributors… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **llama-dev**（project_doc）：The official CLI for development, testing, and automation in the LlamaIndex monorepo. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-dev/README.md`\n- **LlamaIndex Core**（project_doc）：The core python package to the LlamaIndex library. Core classes and abstractions represent the foundational building blocks for LLM applications, most notably, RAG. Such building blocks include abstractions for LLMs, Vector Stores, Embeddings, Storage, Callables and several others. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-core/README.md`\n- **LlamaIndex Instrumentation**（project_doc）：This project provides the instrumentation hooks for observability in LlamaIndex. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-instrumentation/README.md`\n- **LlamaIndex Integrations**（project_doc）：Building LLM applications with LlamaIndex involves building with LlamaIndex core https://github.com/run-llama/llama index/tree/main/llama-index-core as well as with the LlamaIndex Integrations required for your application.Integrations are categorized by type and each are their own Python package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/README.md`\n- **LlamaIndex Utils**（project_doc）：The llama-index-utils library contains common utilities used across various packages. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-utils/README.md`\n- **🔑 KeywordTableIndex**（project_doc）：KeywordTableIndex is a keyword-based table data structure inspired by \"hash tables\" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-core/llama_index/core/indices/keyword_table/README.md`\n- **🔗 SummaryIndex**（project_doc）：SummaryIndex is a simple list-based data structure. During index construction, SummaryIndex takes in a dataset of text documents as input, chunks them up into smaller document chunks, and concatenates them into a list. GPT is not called at all during index construction. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-core/llama_index/core/indices/list/README.md`\n- **🌲 Tree Index**（project_doc）：Currently the tree index refers to the TreeIndex class. It organizes external data into a tree structure that can be queried. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-core/llama_index/core/indices/tree/README.md`\n- **LoadAndSearch Tool**（project_doc）：This Tool Spec is intended to wrap other tools, allowing the Agent to perform separate loading and reading of data. This is very useful for when tools return information larger than or closer to the size of the context window. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md`\n- **LlamaIndex AgentMesh Integration**（project_doc）：AgentMesh trust layer integration for LlamaIndex - enabling cryptographic identity verification and trust-gated agent workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/agent/llama-index-agent-agentmesh/README.md`\n- **LlamaIndex Azure Foundry Agent Integration**（project_doc）：LlamaIndex Azure Foundry Agent Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/agent/llama-index-agent-azure/README.md`\n- **LlamaIndex Callback Integration: Agentops**（project_doc）：LlamaIndex Callback Integration: Agentops 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-agentops/README.md`\n- **LlamaIndex Callbacks Integration: Aim**（project_doc）：LlamaIndex Callbacks Integration: Aim 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-aim/README.md`\n- **Getting Started**（project_doc）：✨🦙 Argilla's LlamaIndex Integration Argilla integration into the LlamaIndex workflow 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md`\n- **LlamaIndex Callbacks Integration: Arize Phoenix**（project_doc）：LlamaIndex Callbacks Integration: Arize Phoenix 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-arize-phoenix/README.md`\n- **LlamaIndex Callbacks Integration: DeepEval**（project_doc）：LlamaIndex Callbacks Integration: DeepEval 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-honeyhive/README.md`\n- **LlamaIndex Callbacks Integration: Langfuse**（project_doc）：LlamaIndex Callbacks Integration: Langfuse 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-langfuse/README.md`\n- **LlamaIndex Callbacks Integration: Literal AI**（project_doc）：LlamaIndex Callbacks Integration: Literal AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-literalai/README.md`\n- **LlamaIndex Callbacks Integration: OpenInference**（project_doc）：LlamaIndex Callbacks Integration: OpenInference 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-openinference/README.md`\n- **LlamaIndex Callbacks Integration: Opik**（project_doc）：LlamaIndex Callbacks Integration: Opik 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-opik/README.md`\n- **LlamaIndex Callbacks Integration: PromptLayer**（project_doc）：LlamaIndex Callbacks Integration: PromptLayer 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-promptlayer/README.md`\n- **LlamaIndex Callbacks Integration: UpTrain**（project_doc）：LlamaIndex Callbacks Integration: UpTrain 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-uptrain/README.md`\n- **LlamaIndex Callbacks Integration: Weights and Biases**（project_doc）：LlamaIndex Callbacks Integration: Weights and Biases 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/callbacks/llama-index-callbacks-wandb/README.md`\n- **LlamaIndex Embeddings Integration: Adapter**（project_doc）：LlamaIndex Embeddings Integration: Adapter 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-adapter/README.md`\n- **LlamaIndex Embeddings Integration: Aleph Alpha**（project_doc）：LlamaIndex Embeddings Integration: Aleph Alpha 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-alephalpha/README.md`\n- **LlamaIndex Embeddings Integration: Alibabacloud Aisearch**（project_doc）：LlamaIndex Embeddings Integration: Alibabacloud Aisearch 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-alibabacloud-aisearch/README.md`\n- **LlamaIndex Embeddings Integration: Anyscale**（project_doc）：LlamaIndex Embeddings Integration: Anyscale 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-anyscale/README.md`\n- **LlamaIndex Embeddings Integration: AutoEmbeddings**（project_doc）：LlamaIndex Embeddings Integration: AutoEmbeddings 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-autoembeddings/README.md`\n- **LlamaIndex Embeddings Integration: Azure AI model inference**（project_doc）：LlamaIndex Embeddings Integration: Azure AI model inference 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-azure-inference/README.md`\n- **LlamaIndex Embeddings Integration: Azure Openai**（project_doc）：LlamaIndex Embeddings Integration: Azure Openai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-azure-openai/README.md`\n- **LlamaIndex Embeddings Integration: Baseten**（project_doc）：LlamaIndex Embeddings Integration: Baseten 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-baseten/README.md`\n- **LlamaIndex Embeddings Integration: Bedrock**（project_doc）：LlamaIndex Embeddings Integration: Bedrock 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-bedrock/README.md`\n- **LlamaIndex Embeddings Integration: Clarifai**（project_doc）：LlamaIndex Embeddings Integration: Clarifai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-clarifai/README.md`\n- **LlamaIndex Embeddings Integration: Clip**（project_doc）：LlamaIndex Embeddings Integration: Clip 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-clip/README.md`\n- **LlamaIndex Embeddings Integration: Cloudflare Workers AI**（project_doc）：LlamaIndex Embeddings Integration: Cloudflare Workers AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-cloudflare-workersai/README.md`\n- **LlamaIndex Embeddings Integration: Cohere**（project_doc）：LlamaIndex Embeddings Integration: Cohere 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-cohere/README.md`\n- **LlamaIndex Embeddings Integration: Dashscope**（project_doc）：LlamaIndex Embeddings Integration: Dashscope 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-dashscope/README.md`\n- **LlamaIndex Embeddings Integration: Databricks**（project_doc）：LlamaIndex Embeddings Integration: Databricks 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-databricks/README.md`\n- **LlamaIndex Embeddings Integration: Deepinfra**（project_doc）：LlamaIndex Embeddings Integration: Deepinfra 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-deepinfra/README.md`\n- **LlamaIndex Embeddings Integration: Elasticsearch**（project_doc）：LlamaIndex Embeddings Integration: Elasticsearch 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-elasticsearch/README.md`\n- **LlamaIndex Embeddings Integration: Fastembed**（project_doc）：LlamaIndex Embeddings Integration: Fastembed 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-fastembed/README.md`\n- **LlamaIndex Embeddings Integration: Fireworks**（project_doc）：LlamaIndex Embeddings Integration: Fireworks 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-fireworks/README.md`\n- **LlamaIndex Embeddings Integration: Gaudi**（project_doc）：LlamaIndex Embeddings Integration: Gaudi 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gaudi/README.md`\n- **GaudiEmbedding Examples**（project_doc）：This folder contains examples showcasing how to use LlamaIndex with Embeddings integration llama index.embeddings.gaudi.GaudiEmbedding on Intel Gaudi. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gaudi/examples/README.md`\n- **LlamaIndex Embeddings Integration: GigaChat**（project_doc）：LlamaIndex Embeddings Integration: GigaChat 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gigachat/README.md`\n- **Google GenAI Embeddings**（project_doc）：This package provides a wrapper around the Google GenAI API, allowing you to use Gemini and Vertex AI embeddings in your projects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-google-genai/README.md`\n- **Heroku Managed Inference Embeddings**（project_doc）：Heroku Managed Inference Embeddings 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-heroku/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface API**（project_doc）：LlamaIndex Embeddings Integration: Huggingface API 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-api/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface OpenVINO**（project_doc）：LlamaIndex Embeddings Integration: Huggingface OpenVINO 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-openvino/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface Optimum Intel**（project_doc）：LlamaIndex Embeddings Integration: Huggingface Optimum Intel 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-optimum-intel/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface Optimum**（project_doc）：LlamaIndex Embeddings Integration: Huggingface Optimum 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-optimum/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface**（project_doc）：LlamaIndex Embeddings Integration: Huggingface 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface/README.md`\n- **LlamaIndex Embeddings Integration: IBM**（project_doc）：LlamaIndex Embeddings Integration: IBM 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-ibm/README.md`\n- **LlamaIndex Embeddings Integration: Instructor**（project_doc）：LlamaIndex Embeddings Integration: Instructor 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-instructor/README.md`\n- **LlamaIndex Embeddings Integration: Ipex Llm**（project_doc）：LlamaIndex Embeddings Integration: Ipex Llm 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-ipex-llm/README.md`\n- **IpexLLMEmbedding Examples**（project_doc）：This folder contains examples showcasing how to use LlamaIndex with ipex-llm Embeddings integration llama index.embeddings.ipex llm.IpexLLMEmbedding on Intel CPU and GPU. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-ipex-llm/examples/README.md`\n- **Isaacus Embeddings**（project_doc）：The llama-index-embeddings-isaacus package contains LlamaIndex integrations for building applications with Isaacus' legal AI embedding models. This integration allows you to easily connect to and use state-of-the-art legal embeddings via the Isaacus API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-isaacus/README.md`\n- **LlamaIndex Embeddings Integration: Jinaai**（project_doc）：LlamaIndex Embeddings Integration: Jinaai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-jinaai/README.md`\n- **LlamaIndex Embeddings Integration: Langchain**（project_doc）：LlamaIndex Embeddings Integration: Langchain 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-langchain/README.md`\n- **LlamaIndex Embeddings Integration: LiteLLM**（project_doc）：LlamaIndex Embeddings Integration: LiteLLM 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-litellm/README.md`\n- **LlamaIndex Embeddings Integration: Ollama**（project_doc）：LlamaIndex Embeddings Integration: Ollama 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-llamafile/README.md`\n- **LlamaIndex Embeddings Integration: Llm Rails**（project_doc）：LlamaIndex Embeddings Integration: Llm Rails 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-llm-rails/README.md`\n- **LlamaIndex Embeddings Integration: Mistralai**（project_doc）：LlamaIndex Embeddings Integration: Mistralai 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-mistralai/README.md`\n- **LlamaIndex Embeddings Integration: MixedbreadAI**（project_doc）：LlamaIndex Embeddings Integration: MixedbreadAI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-mixedbreadai/README.md`\n- **LlamaIndex Embedding Integration: ModelScope**（project_doc）：LlamaIndex Embedding Integration: ModelScope 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md`\n- **LlamaIndex Embeddings Integration: Nebius AI Studio https://studio.nebius.ai/**（project_doc）：LlamaIndex Embeddings Integration: Nebius AI Studio https://studio.nebius.ai/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-nebius/README.md`\n- **LlamaIndex Embeddings Integration: Netmind**（project_doc）：LlamaIndex Embeddings Integration: Netmind 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-netmind/README.md`\n- **LlamaIndex Embeddings Integration: Nomic**（project_doc）：LlamaIndex Embeddings Integration: Nomic 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-nomic/README.md`\n- **LlamaIndex Embeddings Integration: NVIDIA NIM Microservices**（project_doc）：LlamaIndex Embeddings Integration: NVIDIA NIM Microservices 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-nvidia/README.md`\n- **LlamaIndex Embeddings Integration: Oracle Cloud Infrastructure OCI Data Science Service**（project_doc）：LlamaIndex Embeddings Integration: Oracle Cloud Infrastructure OCI Data Science Service 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-oci-data-science/README.md`\n- **LlamaIndex Embeddings Integration: Oracle Cloud Infrastructure OCI Generative AI**（project_doc）：LlamaIndex Embeddings Integration: Oracle Cloud Infrastructure OCI Generative AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-oci-genai/README.md`\n- **LlamaIndex Embeddings Integration: Ollama**（project_doc）：LlamaIndex Embeddings Integration: Ollama 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md`\n- **LlamaIndex Embeddings Integration: OPEA Embeddings**（project_doc）：LlamaIndex Embeddings Integration: OPEA Embeddings 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-opea/README.md`\n- **OpenAILike Embeddings**（project_doc）：This integration allows you to use OpenAI-like embeddings APIs with LlamaIndex. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`llama-index-integrations/embeddings/llama-index-embeddings-openai-like/README.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Building Retrieval Augmented Generation RAG Applications with LlamaIndex**（documentation）：Building Retrieval Augmented Generation RAG Applications with LlamaIndex 证据：`docs/examples/cookbooks/oreilly_course_cookbooks/README.md`\n- **define sample Tool**（documentation）：Putting together an agent in LlamaIndex can be done by defining a set of tools and providing them to our ReActAgent or FunctionAgent implementation. We're using it here with OpenAI, but it can be used with any sufficiently capable LLM. 证据：`docs/src/content/docs/framework/understanding/putting_it_all_together/agents.md`\n- **Use Cases**（documentation）：An \"agent\" is an automated reasoning and decision engine. It takes in a user input/query and can make internal decisions for executing that query in order to return the correct result. The key agent components can include, but are not limited to: 证据：`docs/src/content/docs/framework/use_cases/agents.md`\n- **Google Doc Loader**（documentation）：pip install llama-index-readers-google 证据：`llama-index-integrations/readers/llama-index-readers-google/llama_index/readers/google/docs/README.md`\n- **🎯 Quick Start Guide**（documentation）：Welcome to LlamaIndex ! We’re excited that you want to contribute and become part of our growing community. Whether you're interested in building integrations, fixing bugs, or adding exciting new features, we've made it easy for you to get started. 证据：`docs/src/content/docs/framework/CONTRIBUTING.md`\n- **🗂️ LlamaIndex 🦙**（documentation）：! PyPI - Downloads https://img.shields.io/pypi/dm/llama-index https://pypi.org/project/llama-index/ ! Build https://github.com/run-llama/llama index/actions/workflows/build package.yml/badge.svg https://github.com/run-llama/llama index/actions/workflows/build package.yml ! GitHub contributors https://img.shields.io/github/contributors/jerryjliu/llama index https://github.com/jerryjliu/llama index/graphs/contributors ! Discord https://img.shields.io/discord/1059199217496772688 https://discord.gg/dGcwcsnxhU ! Twitter https://img.shields.io/twitter/follow/llama index https://x.com/llama index ! Reddit https://img.shields.io/reddit/subreddit-subscribers/LlamaIndex?style=plastic&logo=reddit&labe… 证据：`README.md`\n- **llama-dev**（documentation）：The official CLI for development, testing, and automation in the LlamaIndex monorepo. 证据：`llama-dev/README.md`\n- **LlamaIndex Core**（documentation）：The core python package to the LlamaIndex library. Core classes and abstractions represent the foundational building blocks for LLM applications, most notably, RAG. Such building blocks include abstractions for LLMs, Vector Stores, Embeddings, Storage, Callables and several others. 证据：`llama-index-core/README.md`\n- **LlamaIndex Instrumentation**（documentation）：This project provides the instrumentation hooks for observability in LlamaIndex. 证据：`llama-index-instrumentation/README.md`\n- **LlamaIndex Integrations**（documentation）：Building LLM applications with LlamaIndex involves building with LlamaIndex core https://github.com/run-llama/llama index/tree/main/llama-index-core as well as with the LlamaIndex Integrations required for your application.Integrations are categorized by type and each are their own Python package. 证据：`llama-index-integrations/README.md`\n- **LlamaIndex Utils**（documentation）：The llama-index-utils library contains common utilities used across various packages. 证据：`llama-index-utils/README.md`\n- **🔑 KeywordTableIndex**（documentation）：KeywordTableIndex is a keyword-based table data structure inspired by \"hash tables\" . 证据：`llama-index-core/llama_index/core/indices/keyword_table/README.md`\n- **🔗 SummaryIndex**（documentation）：SummaryIndex is a simple list-based data structure. During index construction, SummaryIndex takes in a dataset of text documents as input, chunks them up into smaller document chunks, and concatenates them into a list. GPT is not called at all during index construction. 证据：`llama-index-core/llama_index/core/indices/list/README.md`\n- **🌲 Tree Index**（documentation）：Currently the tree index refers to the TreeIndex class. It organizes external data into a tree structure that can be queried. 证据：`llama-index-core/llama_index/core/indices/tree/README.md`\n- **LoadAndSearch Tool**（documentation）：This Tool Spec is intended to wrap other tools, allowing the Agent to perform separate loading and reading of data. This is very useful for when tools return information larger than or closer to the size of the context window. 证据：`llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md`\n- **LlamaIndex AgentMesh Integration**（documentation）：AgentMesh trust layer integration for LlamaIndex - enabling cryptographic identity verification and trust-gated agent workflows. 证据：`llama-index-integrations/agent/llama-index-agent-agentmesh/README.md`\n- **LlamaIndex Azure Foundry Agent Integration**（documentation）：LlamaIndex Azure Foundry Agent Integration 证据：`llama-index-integrations/agent/llama-index-agent-azure/README.md`\n- **LlamaIndex Callback Integration: Agentops**（documentation）：LlamaIndex Callback Integration: Agentops 证据：`llama-index-integrations/callbacks/llama-index-callbacks-agentops/README.md`\n- **LlamaIndex Callbacks Integration: Aim**（documentation）：LlamaIndex Callbacks Integration: Aim 证据：`llama-index-integrations/callbacks/llama-index-callbacks-aim/README.md`\n- **Getting Started**（documentation）：✨🦙 Argilla's LlamaIndex Integration Argilla integration into the LlamaIndex workflow 证据：`llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md`\n- **LlamaIndex Callbacks Integration: Arize Phoenix**（documentation）：LlamaIndex Callbacks Integration: Arize Phoenix 证据：`llama-index-integrations/callbacks/llama-index-callbacks-arize-phoenix/README.md`\n- **LlamaIndex Callbacks Integration: DeepEval**（documentation）：LlamaIndex Callbacks Integration: DeepEval 证据：`llama-index-integrations/callbacks/llama-index-callbacks-honeyhive/README.md`\n- **LlamaIndex Callbacks Integration: Langfuse**（documentation）：LlamaIndex Callbacks Integration: Langfuse 证据：`llama-index-integrations/callbacks/llama-index-callbacks-langfuse/README.md`\n- **LlamaIndex Callbacks Integration: Literal AI**（documentation）：LlamaIndex Callbacks Integration: Literal AI 证据：`llama-index-integrations/callbacks/llama-index-callbacks-literalai/README.md`\n- **LlamaIndex Callbacks Integration: OpenInference**（documentation）：LlamaIndex Callbacks Integration: OpenInference 证据：`llama-index-integrations/callbacks/llama-index-callbacks-openinference/README.md`\n- **LlamaIndex Callbacks Integration: Opik**（documentation）：LlamaIndex Callbacks Integration: Opik 证据：`llama-index-integrations/callbacks/llama-index-callbacks-opik/README.md`\n- **LlamaIndex Callbacks Integration: PromptLayer**（documentation）：LlamaIndex Callbacks Integration: PromptLayer 证据：`llama-index-integrations/callbacks/llama-index-callbacks-promptlayer/README.md`\n- **LlamaIndex Callbacks Integration: UpTrain**（documentation）：LlamaIndex Callbacks Integration: UpTrain 证据：`llama-index-integrations/callbacks/llama-index-callbacks-uptrain/README.md`\n- **LlamaIndex Callbacks Integration: Weights and Biases**（documentation）：LlamaIndex Callbacks Integration: Weights and Biases 证据：`llama-index-integrations/callbacks/llama-index-callbacks-wandb/README.md`\n- **LlamaIndex Embeddings Integration: Adapter**（documentation）：LlamaIndex Embeddings Integration: Adapter 证据：`llama-index-integrations/embeddings/llama-index-embeddings-adapter/README.md`\n- **LlamaIndex Embeddings Integration: Aleph Alpha**（documentation）：LlamaIndex Embeddings Integration: Aleph Alpha 证据：`llama-index-integrations/embeddings/llama-index-embeddings-alephalpha/README.md`\n- **LlamaIndex Embeddings Integration: Alibabacloud Aisearch**（documentation）：LlamaIndex Embeddings Integration: Alibabacloud Aisearch 证据：`llama-index-integrations/embeddings/llama-index-embeddings-alibabacloud-aisearch/README.md`\n- **LlamaIndex Embeddings Integration: Anyscale**（documentation）：LlamaIndex Embeddings Integration: Anyscale 证据：`llama-index-integrations/embeddings/llama-index-embeddings-anyscale/README.md`\n- **LlamaIndex Embeddings Integration: AutoEmbeddings**（documentation）：LlamaIndex Embeddings Integration: AutoEmbeddings 证据：`llama-index-integrations/embeddings/llama-index-embeddings-autoembeddings/README.md`\n- **LlamaIndex Embeddings Integration: Azure AI model inference**（documentation）：LlamaIndex Embeddings Integration: Azure AI model inference 证据：`llama-index-integrations/embeddings/llama-index-embeddings-azure-inference/README.md`\n- **LlamaIndex Embeddings Integration: Azure Openai**（documentation）：LlamaIndex Embeddings Integration: Azure Openai 证据：`llama-index-integrations/embeddings/llama-index-embeddings-azure-openai/README.md`\n- **LlamaIndex Embeddings Integration: Baseten**（documentation）：LlamaIndex Embeddings Integration: Baseten 证据：`llama-index-integrations/embeddings/llama-index-embeddings-baseten/README.md`\n- **LlamaIndex Embeddings Integration: Bedrock**（documentation）：LlamaIndex Embeddings Integration: Bedrock 证据：`llama-index-integrations/embeddings/llama-index-embeddings-bedrock/README.md`\n- **LlamaIndex Embeddings Integration: Clarifai**（documentation）：LlamaIndex Embeddings Integration: Clarifai 证据：`llama-index-integrations/embeddings/llama-index-embeddings-clarifai/README.md`\n- **LlamaIndex Embeddings Integration: Clip**（documentation）：LlamaIndex Embeddings Integration: Clip 证据：`llama-index-integrations/embeddings/llama-index-embeddings-clip/README.md`\n- **LlamaIndex Embeddings Integration: Cloudflare Workers AI**（documentation）：LlamaIndex Embeddings Integration: Cloudflare Workers AI 证据：`llama-index-integrations/embeddings/llama-index-embeddings-cloudflare-workersai/README.md`\n- **LlamaIndex Embeddings Integration: Cohere**（documentation）：LlamaIndex Embeddings Integration: Cohere 证据：`llama-index-integrations/embeddings/llama-index-embeddings-cohere/README.md`\n- **LlamaIndex Embeddings Integration: Dashscope**（documentation）：LlamaIndex Embeddings Integration: Dashscope 证据：`llama-index-integrations/embeddings/llama-index-embeddings-dashscope/README.md`\n- **LlamaIndex Embeddings Integration: Databricks**（documentation）：LlamaIndex Embeddings Integration: Databricks 证据：`llama-index-integrations/embeddings/llama-index-embeddings-databricks/README.md`\n- **LlamaIndex Embeddings Integration: Deepinfra**（documentation）：LlamaIndex Embeddings Integration: Deepinfra 证据：`llama-index-integrations/embeddings/llama-index-embeddings-deepinfra/README.md`\n- **LlamaIndex Embeddings Integration: Elasticsearch**（documentation）：LlamaIndex Embeddings Integration: Elasticsearch 证据：`llama-index-integrations/embeddings/llama-index-embeddings-elasticsearch/README.md`\n- **LlamaIndex Embeddings Integration: Fastembed**（documentation）：LlamaIndex Embeddings Integration: Fastembed 证据：`llama-index-integrations/embeddings/llama-index-embeddings-fastembed/README.md`\n- **LlamaIndex Embeddings Integration: Fireworks**（documentation）：LlamaIndex Embeddings Integration: Fireworks 证据：`llama-index-integrations/embeddings/llama-index-embeddings-fireworks/README.md`\n- **LlamaIndex Embeddings Integration: Gaudi**（documentation）：LlamaIndex Embeddings Integration: Gaudi 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gaudi/README.md`\n- **GaudiEmbedding Examples**（documentation）：This folder contains examples showcasing how to use LlamaIndex with Embeddings integration llama index.embeddings.gaudi.GaudiEmbedding on Intel Gaudi. 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gaudi/examples/README.md`\n- **LlamaIndex Embeddings Integration: GigaChat**（documentation）：LlamaIndex Embeddings Integration: GigaChat 证据：`llama-index-integrations/embeddings/llama-index-embeddings-gigachat/README.md`\n- **Google GenAI Embeddings**（documentation）：This package provides a wrapper around the Google GenAI API, allowing you to use Gemini and Vertex AI embeddings in your projects. 证据：`llama-index-integrations/embeddings/llama-index-embeddings-google-genai/README.md`\n- **Heroku Managed Inference Embeddings**（documentation）：Heroku Managed Inference Embeddings 证据：`llama-index-integrations/embeddings/llama-index-embeddings-heroku/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface API**（documentation）：LlamaIndex Embeddings Integration: Huggingface API 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-api/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface OpenVINO**（documentation）：LlamaIndex Embeddings Integration: Huggingface OpenVINO 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-openvino/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface Optimum Intel**（documentation）：LlamaIndex Embeddings Integration: Huggingface Optimum Intel 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-optimum-intel/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface Optimum**（documentation）：LlamaIndex Embeddings Integration: Huggingface Optimum 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface-optimum/README.md`\n- **LlamaIndex Embeddings Integration: Huggingface**（documentation）：LlamaIndex Embeddings Integration: Huggingface 证据：`llama-index-integrations/embeddings/llama-index-embeddings-huggingface/README.md`\n- **LlamaIndex Embeddings Integration: IBM**（documentation）：LlamaIndex Embeddings Integration: IBM 证据：`llama-index-integrations/embeddings/llama-index-embeddings-ibm/README.md`\n- **LlamaIndex Embeddings Integration: Instructor**（documentation）：LlamaIndex Embeddings Integration: Instructor 证据：`llama-index-integrations/embeddings/llama-index-embeddings-instructor/README.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/examples/cookbooks/oreilly_course_cookbooks/README.md`, `docs/src/content/docs/framework/understanding/putting_it_all_together/agents.md`, `docs/src/content/docs/framework/use_cases/agents.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/examples/cookbooks/oreilly_course_cookbooks/README.md`, `docs/src/content/docs/framework/understanding/putting_it_all_together/agents.md`, `docs/src/content/docs/framework/use_cases/agents.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\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- **Introduction to LlamaIndex**：importance `high`\n - source_paths: README.md, llama-index-core/llama_index/core/__init__.py, docs/src/content/docs/framework/getting_started/concepts.mdx\n- **Quick Start Guide**：importance `high`\n - source_paths: docs/src/content/docs/framework/getting_started/installation.mdx, docs/src/content/docs/framework/getting_started/starter_example.mdx\n- **Core Architecture**：importance `high`\n - source_paths: llama-index-core/llama_index/core/base/llms/base.py, llama-index-core/llama_index/core/base/embeddings/base.py, llama-index-core/llama_index/core/base/response/schema.py, llama-index-core/llama_index/core/types.py\n- **Integration Architecture**：importance `medium`\n - source_paths: llama-index-integrations/README.md, llama-index-integrations/llms/llama-index-llms-openai/llama_index/llms/openai/base.py, llama-index-integrations/embeddings/llama-index-embeddings-openai/llama_index/embeddings/openai/base.py\n- **Documents and Nodes**：importance `high`\n - source_paths: llama-index-core/llama_index/core/schema.py, llama-index-core/llama_index/core/node_parser/interface.py, llama-index-core/llama_index/core/readers/base.py, llama-index-core/llama_index/core/node_parser/text/sentence.py\n- **Storage Systems**：importance `high`\n - source_paths: llama-index-core/llama_index/core/storage/storage_context.py, llama-index-core/llama_index/core/storage/docstore/simple_docstore.py, llama-index-core/llama_index/core/storage/index_store/simple_index_store.py, llama-index-core/llama_index/core/storage/chat_store/simple_chat_store.py\n- **Query Engines**：importance `high`\n - source_paths: llama-index-core/llama_index/core/query_engine/retriever_query_engine.py, llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py, llama-index-core/llama_index/core/response_synthesizers/base.py, llama-index-core/llama_index/core/indices/vector_store/base.py\n- **Retrieval and Reranking**：importance `high`\n - source_paths: llama-index-core/llama_index/core/retrievers/recursive_retriever.py, llama-index-core/llama_index/core/postprocessor/llm_rerank.py, llama-index-core/llama_index/core/postprocessor/node.py, llama-index-core/llama_index/core/indices/property_graph/retriever.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `23bd65aaf79ffed587af35f325738b1580b35dea`\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: 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 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo: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- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/run-llama/llama_index 项目说明书\n\n生成时间：2026-05-15 21:38:00 UTC\n\n## 目录\n\n- [Introduction to LlamaIndex](#introduction)\n- [Quick Start Guide](#quickstart)\n- [Core Architecture](#core-architecture)\n- [Integration Architecture](#integration-architecture)\n- [Documents and Nodes](#documents-nodes)\n- [Storage Systems](#storage-systems)\n- [Query Engines](#query-engines)\n- [Retrieval and Reranking](#retrieval-reranking)\n- [Agent Framework](#agent-framework)\n- [Memory Systems](#memory-systems)\n\n\n\n## Introduction to LlamaIndex\n\n### 相关页面\n\n相关主题：[Core Architecture](#core-architecture), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/run-llama/llama_index/blob/main/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/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/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/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 \n\n# Introduction to LlamaIndex\n\nLlamaIndex is a comprehensive data framework designed for building LLM (Large Language Model) applications. It provides the essential tools, abstractions, and integrations needed to connect custom data sources to LLMs for retrieval-augmented generation (RAG), question-answering systems, and other AI-powered applications.\n\n## Overview\n\nLlamaIndex serves as the foundational layer for building AI applications that require sophisticated data ingestion, indexing, and querying capabilities. The framework enables developers to:\n\n- Ingest data from various sources (PDFs, documents, websites, databases)\n- Process and chunk data into optimal segments for LLM consumption\n- Create vector indices for efficient semantic search\n- Build query engines and retrieval pipelines\n- Integrate with hundreds of external services and model providers\n\n资料来源：[README.md:1-20](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Core Architecture\n\nThe LlamaIndex framework follows a modular architecture with distinct components that work together to provide end-to-end data pipeline capabilities.\n\n### Package Structure\n\nLlamaIndex offers two primary installation methods to accommodate different use cases:\n\n| Package | Description | Use Case |\n|---------|-------------|----------|\n| `llama-index` | Starter package with core + selected integrations | Quick start, common setups |\n| `llama-index-core` | Core package only | Custom, minimal deployments |\n\n资料来源：[README.md:45-55](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n### Import Patterns\n\nThe framework uses a namespaced import system that distinguishes between core modules and integration packages:\n\n```python\n# Core modules (included in llama-index-core)\nfrom llama_index.core.xxx import ClassABC\n\n# Integration modules (from separate packages)\nfrom llama_index.xxx.yyy import SubclassABC\n\n# Concrete examples\nfrom llama_index.core.llms import LLM\nfrom llama_index.llms.openai import OpenAI\n```\n\n资料来源：[README.md:56-68](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Data Flow Architecture\n\nThe following diagram illustrates the typical data flow in a LlamaIndex application:\n\n```mermaid\ngraph TD\n A[Data Sources] --> B[Readers/Loaders]\n B --> C[Documents]\n C --> D[Node Parsers]\n D --> E[Nodes/Chunks]\n E --> F[Vector Index]\n F --> G[Retriever]\n G --> H[Query Engine]\n H --> I[LLM Response]\n \n A1[Web Pages] --> B\n A2[PDFs] --> B\n A3[Databases] --> B\n A4[APIs] --> B\n```\n\n## Key Components\n\n### 1. Document Loaders\n\nDocument loaders (Readers) are responsible for ingesting data from external sources. LlamaIndex provides a vast ecosystem of readers:\n\n| Reader | Purpose | Source |\n|--------|---------|--------|\n| `WikipediaReader` | Load Wikipedia pages | [llama-index-readers-wikipedia](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md) |\n| `WholeSiteReader` | Scrape entire websites | [llama-index-readers-web](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| `DoclingReader` | Parse PDFs, DOCX, HTML | [llama-index-readers-docling](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md) |\n| `RemoteDepthReader` | Extract from URLs recursively | [llama-index-readers-remote-depth](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/README.md) |\n\n#### Wikipedia Reader Example\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-readers-wikipedia/README.md:1-25](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n\n#### Docling Reader Example\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资料来源：[llama-index-readers-docling/README.md:1-30](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)\n\n### 2. Indices\n\nIndices organize documents for efficient retrieval. LlamaIndex supports both managed indices and customizable self-hosted options.\n\n#### Managed Indices\n\nManaged indices like `VectaraIndex` provide fully hosted solutions:\n\n```python\nfrom llama_index.indices.managed.vectara import VectaraIndex\nfrom llama_index.core.schema import Document, MediaResource\n\ndocs = [\n Document(\n id_=\"doc1\",\n text_resource=MediaResource(\n text=\"This is test text for Vectara integration.\",\n ),\n ),\n]\nindex = VectaraIndex.from_documents(docs)\n```\n\n资料来源：[llama-index-indices-managed-vectara/README.md:30-50](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n\n### 3. LLM Integrations\n\nLlamaIndex provides integrations with numerous LLM providers through a standardized interface:\n\n```python\n# Example: Contextual LLM Integration\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-llms-contextual/README.md:1-20](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-contextual/README.md)\n\n## Usage Patterns\n\n### Building a Simple RAG Pipeline\n\nThe most common pattern involves loading documents, creating an index, and querying it:\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.docling import DoclingReader\n\n# Step 1: Load documents\nreader = DoclingReader()\ndocuments = reader.load_data(file_path=\"document.pdf\")\n\n# Step 2: Create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Step 3: Query\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"Summarize this document\")\n```\n\n### Retrieval-Only Pattern\n\nFor applications requiring only retrieval without generation:\n\n```python\nretriever = index.as_retriever(similarity_top_k=2)\nresults = retriever.retrieve(\"How will users feel about this new tool?\")\n```\n\n资料来源：[llama-index-indices-managed-vectara/README.md:50-65](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)\n\n### LangChain Integration\n\nLlamaIndex components can be used as tools within LangChain agents:\n\n```python\nfrom langchain.agents import initialize_agent, Tool\nfrom langchain.llms import OpenAI\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.readers.web import WholeSiteReader\n\n# Initialize scraper\nscraper = WholeSiteReader(prefix=\"https://docs.llamaindex.ai/en/stable/\", max_depth=10)\ndocuments = scraper.load_data(base_url=\"https://docs.llamaindex.ai/en/stable/\")\n\n# Create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Define tools\ntools = [\n Tool(\n name=\"Website Index\",\n func=lambda q: index.query(q),\n description=\"Useful for answering questions about text on websites.\",\n ),\n]\n```\n\n资料来源：[llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1-40](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\n## LlamaParse Platform\n\n**LlamaParse** is a complementary platform (separate from the open-source LlamaIndex framework) focused on document agents and agentic OCR:\n\n| Component | Function |\n|-----------|----------|\n| **Parse** | Agentic OCR and document parsing (130+ formats) |\n| **Extract** | Structured data extraction from documents |\n| **Index** | Ingest, index, and RAG pipelines |\n| **Split** | Split large documents into subcategories |\n\n资料来源：[README.md:75-85](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Ecosystem Overview\n\nLlamaIndex maintains an extensive ecosystem with over 300 integration packages available through LlamaHub:\n\n```mermaid\ngraph LR\n subgraph \"Data Sources\"\n Web[Web]\n PDFs[PDFs]\n DB[Databases]\n APIs[APIs]\n end\n \n subgraph \"LlamaIndex Core\"\n Docs[Documents]\n Nodes[Nodes]\n Indices[Indices]\n end\n \n subgraph \"LLM Providers\"\n OpenAI[OpenAI]\n HuggingFace[HF]\n Local[Local Models]\n end\n \n Web --> Docs\n PDFs --> Docs\n DB --> Docs\n APIs --> Docs\n Docs --> Indices\n Indices --> OpenAI\n Indices --> HuggingFace\n Indices --> Local\n```\n\n## Configuration Options\n\n### Common Reader Configuration Parameters\n\n| Parameter | Type | Description | Example |\n|-----------|------|-------------|---------|\n| `file_path` | str | Path to input file/URL | `\"document.pdf\"` |\n| `prefix` | str | URL prefix for filtering | `\"https://example.com/\"` |\n| `max_depth` | int | Maximum recursion depth | `10` |\n| `where` | dict | Metadata filter condition | `{\"category\": \"AI\"}` |\n| `query` | list | Search query text | `[\"search term\"]` |\n\n资料来源：[llama-index-readers-chroma/README.md:1-20](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-chroma/README.md)\n\n## Installation\n\n### Quick Start (Recommended)\n\n```bash\npip install llama-index\n```\n\n### Minimal Installation\n\n```bash\npip install llama-index-core\n```\n\n### Individual Integrations\n\n```bash\npip install llama-index-readers-wikipedia\npip install llama-index-readers-docling\npip install llama-index-llms-openai\n```\n\n## Citation\n\nIf you use LlamaIndex in academic work, cite as:\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-105](https://github.com/run-llama/llama_index/blob/main/README.md)\n\n## Next Steps\n\nTo continue learning LlamaIndex:\n\n1. **Getting Started** - Follow the [starter example](https://docs.llamaindex.ai/en/stable/getting_started/starter_example.html)\n2. **Concepts** - Understand core concepts like Documents, Nodes, and Indices\n3. **LlamaHub** - Browse [300+ integrations](https://llamahub.ai/) for various data sources and LLM providers\n4. **Examples** - Explore [Jupyter notebooks](https://github.com/run-llama/llama_index/blob/main/docs/examples/) for detailed use cases\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to LlamaIndex](#introduction), [Documents and Nodes](#documents-nodes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-dev/README.md](https://github.com/run-llama/llama_index/blob/main/llama-dev/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/llms/llama-index-llms-mistralai/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-mistralai/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- [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/llms/llama-index-llms-modelscope/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-modelscope/README.md)\n \n\n# Quick Start Guide\n\nThis guide provides a comprehensive introduction to getting started with LlamaIndex, covering environment setup, core installation methods, and essential development workflows.\n\n## Prerequisites\n\nBefore beginning, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Python | 3.8 or higher |\n| Package Manager | `uv` (recommended) or `pip` |\n| Operating System | Unix-like (Linux, macOS), Windows with WSL |\n| Git | Latest stable version |\n\n## Environment Setup\n\n### Creating a Virtual Environment\n\nLlamaIndex recommends using `uv` for dependency management. Create a virtual environment as follows:\n\n```bash\nuv venv\nsource .venv/bin/activate\n```\n\n资料来源：[llama-dev/README.md:11]()\n\n### Installing the Development CLI\n\nThe `llama-dev` CLI tool is the official command-line interface for development, testing, and automation in the LlamaIndex monorepo.\n\nInstall it in editable mode:\n\n```bash\nuv pip install -e .\n```\n\nAfter installation, verify the CLI is available:\n\n```bash\nllama-dev --help\n```\n\n资料来源：[llama-dev/README.md:12-18]()\n\n## Core Concepts\n\n```mermaid\ngraph TD\n A[LlamaIndex Project] --> B[Core Package: llama-index-core]\n A --> C[LLM Integrations]\n A --> D[Reader Integrations]\n A --> E[Callback Integrations]\n B --> F[VectorStoreIndex]\n B --> G[ServiceContext]\n B --> H[Document Loading]\n```\n\nThe LlamaIndex framework consists of several key components:\n\n| Component | Purpose |\n|-----------|---------|\n| `llama-index-core` | Core framework functionality including indexing and querying |\n| LLM Integrations | Connectors for various language model providers |\n| Reader Integrations | Data loaders for different document sources |\n| Callback Integrations | Monitoring and logging capabilities |\n\n## Package Management\n\n### Querying Package Information\n\nView information about specific packages in the monorepo:\n\n```bash\n# Get info for a specific package\nllama-dev pkg info llama-index-core\n\n# Get info for all packages\nllama-dev pkg info --all\n```\n\n### Executing Commands in Package Directories\n\nRun commands within the context of specific packages:\n\n```bash\n# Run a command in a specific package\nllama-dev pkg exec --cmd \"uv sync\" llama-index-core\n\n# Run a command in all packages\nllama-dev pkg exec --cmd \"uv sync\" --all\n\n# Exit at first error\nllama-dev pkg exec --cmd \"uv\" --all --fail-fast\n```\n\n资料来源：[llama-dev/README.md:26-41]()\n\n## Testing\n\n### Running Tests Across the Monorepo\n\nExecute tests for specific packages or across all packages:\n\n```bash\n# Run tests for a specific package\nllama-dev pkg test llama-index-core\n\n# Run tests for all packages\nllama-dev pkg test --all\n```\n\n### Quick Test Verification\n\nAfter making changes, verify core functionality:\n\n```bash\nllama-dev pkg exec --cmd \"python -m pytest\" llama-index-core\n```\n\n## Basic LLM Integration Usage\n\n### Initializing an LLM\n\nDifferent LLM providers follow similar initialization patterns:\n\n```python\nfrom llama_index.llms.ollama import Ollama\n\n# Initialize Ollama LLM\nllm = Ollama(model=\"llama3.1:latest\", request_timeout=120.0)\n```\n\n```python\nfrom llama_index.llms.mistralai import MistralAI\n\nllm = MistralAI(api_key=\"\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:30-35]()\n资料来源：[llama-index-integrations/llms/llama-index-llms-mistralai/README.md:16-18]()\n\n### Generating Completions\n\n```python\n# Simple completion\nresp = llm.complete(\"Who is Paul Graham?\")\nprint(resp)\n```\n\n```python\n# Chat completion with messages\nfrom llama_index.core.llms import ChatMessage\n\nmessages = [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=\"You are a helpful assistant.\"\n ),\n ChatMessage(role=MessageRole.USER, content=\"How to make cake?\"),\n]\nresp = llm.chat(messages)\nprint(resp)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-modelscope/README.md:24-37]()\n\n### Streaming Responses\n\n```python\n# Stream completions\nresp = llm.stream_complete(\"Paul Graham is \")\nfor r in resp:\n print(r.delta, end=\"\")\n```\n\n```python\n# Stream chat responses\nresp = llm.stream_chat([message])\nfor r in resp:\n print(r.delta, end=\"\")\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-mistralai/README.md:40-48]()\n\n## Building an Index from Documents\n\n### Basic Index Creation\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\n# Create index from documents\nindex = VectorStoreIndex.from_documents(documents)\n```\n\n```python\n# Query the index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"What is the main topic?\")\nprint(response)\n```\n\n### Loading Data from URLs\n\n```python\nfrom llama_index.readers.web import WholeSiteReader\n\n# Initialize the scraper\nscraper = WholeSiteReader(\n prefix=\"https://docs.llamaindex.ai/en/stable/\",\n max_depth=10,\n)\n\n# Start scraping from a base URL\ndocuments = scraper.load_data(\n base_url=\"https://docs.llamaindex.ai/en/stable/\"\n)\n\n# Create index\nindex = VectorStoreIndex.from_documents(documents)\nindex.query(\"What language is on this website?\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:14-34]()\n\n## Configuration Options\n\n### Key Parameters\n\n| Parameter | Description | Default Value |\n|-----------|-------------|---------------|\n| `model` | LLM model identifier | Required |\n| `api_key` | API key for the provider | Required for cloud providers |\n| `request_timeout` | Request timeout in seconds | 30.0 |\n| `temperature` | Sampling temperature | 0.7 |\n| `max_tokens` | Maximum tokens to generate | Provider-specific |\n| `context_window` | Maximum context length | Provider-specific |\n\n### Environment Variables\n\nSet API keys as environment variables before initialization:\n\n```bash\nexport KONKO_API_KEY=\nexport OPENAI_API_KEY=\n```\n\n```python\nimport os\nos.environ[\"KONKO_API_KEY\"] = \"\"\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-konko/README.md:15-20]()\n\n## Common Workflows\n\n```mermaid\ngraph LR\n A[Setup Environment] --> B[Install llama-dev]\n B --> C[Explore Packages]\n C --> D{Development Goal}\n D -->|Testing| E[Run Tests]\n D -->|Integration| F[Configure LLM]\n D -->|Data Loading| G[Set up Readers]\n E --> H[Modify Code]\n F --> H\n G --> H\n H --> I[Verify Changes]\n I --> E\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| CLI not found | Ensure virtual environment is activated |\n| API key errors | Verify environment variables are set |\n| Package import errors | Run `uv sync` in the package directory |\n| Timeout errors | Increase `request_timeout` parameter |\n\n### Verification Commands\n\n```bash\n# Check installation\nllama-dev --version\n\n# Verify package structure\nllama-dev pkg info --all\n\n# Test core imports\npython -c \"import llama_index; print(llama_index.__version__)\"\n```\n\n## Next Steps\n\nAfter completing this quick start guide:\n\n1. Explore specific [LLM integrations](#core-llm-integrations) for your preferred provider\n2. Review [reader integrations](#data-loading) for your data sources\n3. Study the [core API documentation](#key-concepts) for advanced indexing strategies\n4. Join the community for support and updates\n\n---\n\n\n\n## Core Architecture\n\n### 相关页面\n\n相关主题：[Introduction to LlamaIndex](#introduction), [Integration Architecture](#integration-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/base/llms/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/llms/base.py)\n- [llama-index-core/llama_index/core/base/embeddings/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/embeddings/base.py)\n- [llama-index-core/llama_index/core/base/response/schema.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/base/response/schema.py)\n- [llama-index-core/llama_index/core/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/types.py)\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/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/node_parser/node.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/node.py)\n- [llama-index-core/llama_index/core/response/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/response/__init__.py)\n \n\n# Core Architecture\n\n## Overview\n\nLlamaIndex is a data framework for building LLM-powered applications. The Core Architecture establishes the fundamental building blocks that enable developers to connect large language models with their custom data sources. This architectural foundation provides a layered, modular approach where each component—from language model interfaces to response handling—follows consistent patterns and abstractions.\n\nThe core architecture serves as the abstraction layer between raw data ingestion and sophisticated LLM-powered querying. It separates concerns by defining clear interfaces for language models (LLMs), embedding services, document processing, indexing, and response generation. This design allows developers to swap implementations, extend functionality, and maintain clean separation between components.\n\n## System Components\n\n### High-Level Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph \"Data Layer\"\n Documents[Documents]\n Nodes[Nodes]\n Index[Index]\n end\n \n subgraph \"Core Abstractions\"\n LLMs[LLM Base]\n Embeddings[Embedding Base]\n Response[Response Schema]\n end\n \n subgraph \"Service Layer\"\n VectorStore[Vector Store]\n StorageContext[Storage Context]\n end\n \n subgraph \"Application Layer\"\n Query[Query Engine]\n Chat[Chat Engine]\n Agent[Agent]\n end\n \n Documents --> NodeParser\n NodeParser --> Nodes\n Nodes --> Index\n Index --> Query\n Query --> Response\n LLMs --> Query\n Embeddings --> Index\n```\n\n## Language Model (LLM) Abstraction\n\n### Purpose and Role\n\nThe LLM base abstraction (`llama_index.core.base.llms.base`) defines the contract that all language model implementations must follow. This abstraction enables LlamaIndex to support multiple LLM providers—including OpenAI, Anthropic, local models, and custom implementations—through a unified interface.\n\n资料来源：[llama-index-core/llama_index/core/base/llms/base.py:1-50]()\n\n### Base LLM Interface\n\nThe `LLM` base class provides the following core methods:\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `complete()` | Synchronous text completion | `prompt: str`, `formatted: bool = False`, `**kwargs` |\n| `stream_complete()` | Streaming text completion | `prompt: str`, `formatted: bool = False`, `**kwargs` |\n| `chat()` | Synchronous chat completion | `messages: List[ChatMessage]`, `**kwargs` |\n| `stream_chat()` | Streaming chat completion | `messages: List[ChatMessage]`, `**kwargs` |\n\n### LLM Class Hierarchy\n\n```mermaid\nclassDiagram\n class LLM {\n <>\n +complete()\n +stream_complete()\n +chat()\n +stream_chat()\n +metadata: LLMMetadata\n }\n \n class LLMMetadata {\n +model: str\n +temperature: float\n +top_p: int\n +max_tokens: Optional[int]\n +context_window: int\n +is_chat_model: bool\n +is_function_calling_model: bool\n }\n \n class ChatMessage {\n +role: MessageRole\n +content: str\n +additional_kwargs: Dict\n }\n \n LLM --> LLMMetadata\n LLM --> ChatMessage\n```\n\n资料来源：[llama-index-core/llama_index/core/base/llms/base.py:50-120]()\n\n### Message Roles\n\nThe `MessageRole` enum defines valid roles for chat messages:\n\n| Role | Description |\n|------|-------------|\n| `SYSTEM` | System-level instructions |\n| `USER` | User-generated content |\n| `ASSISTANT` | Model-generated responses |\n| `FUNCTION` | Function call results |\n\n## Embedding Abstraction\n\n### Purpose and Role\n\nThe embedding base (`llama_index.core.base.embeddings.base`) provides the interface for text vectorization. Embeddings transform textual content into numerical vectors that enable semantic similarity searches. This abstraction supports various embedding providers while maintaining a consistent API.\n\n资料来源：[llama-index-core/llama_index/core/base/embeddings/base.py:1-60]()\n\n### Embedding Interface Methods\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `get_query_embedding()` | Embed a single query string | `List[float]` |\n| `get_text_embedding()` | Embed a single text string | `List[float]` |\n| `get_text_embedding_batch()` | Embed multiple texts in batch | `List[List[float]]` |\n| `get_query_embedding_batch()` | Embed multiple queries in batch | `List[List[float]]]` |\n\n### Embedding Configuration\n\n```mermaid\ngraph LR\n A[Text Input] --> B[Embedding Model]\n B --> C[Dimension: 384-1536]\n C --> D[Normalized Vector]\n```\n\n资料来源：[llama-index-core/llama_index/core/base/embeddings/base.py:60-100]()\n\n## Response Schema\n\n### Purpose and Role\n\nThe response schema (`llama_index.core.base.response.schema`) defines the data structures used throughout LlamaIndex for returning query results, streaming responses, and structured outputs. This ensures consistent response handling across different query types and engines.\n\n资料来源：[llama-index-core/llama_index/core/base/response/schema.py:1-80]()\n\n### Core Response Models\n\n| Class | Purpose |\n|-------|---------|\n| `Response` | Wraps text responses with sources |\n| `StreamingResponse` | Handles streaming token outputs |\n| `ResponseMode` | Enum for response generation modes |\n| `Sources` | Container for source nodes and metadata |\n\n### Response Mode Enumeration\n\n```mermaid\ngraph TD\n A[Query] --> B{Response Mode}\n B --> C[default]\n B --> D[refine]\n B --> E[compact]\n B --> F[accumulate]\n B --> G[compact_accumulate]\n \n C --> H[Single pass response]\n D --> I[Iterative refinement]\n E --> J[Compact and respond]\n F --> K[Aggregate node responses]\n G --> L[Compact then accumulate]\n```\n\n资料来源：[llama-index-core/llama_index/core/base/response/schema.py:30-50]()\n\n## Core Types System\n\n### Type Definitions\n\nThe types module (`llama_index.core.types`) defines foundational enumerations and type aliases used throughout the framework:\n\n| Type | Description |\n|------|-------------|\n| `ModelType` | Defines model categories (e.g., `LLM`, `EMBEDDING`) |\n| `PromptType` | Categorizes prompts (e.g., `SUMMARY`, `QUERY`) |\n| `NodeType` | Defines node kinds (e.g., `TEXT`, `DOCUMENT`) |\n\n资料来源：[llama-index-core/llama_index/core/types.py:1-60]()\n\n### Node Parser Types\n\n```mermaid\nclassDiagram\n class Node {\n <>\n +id_: str\n +embedding: Optional[List[float]]\n +metadata: Dict[str, Any]\n +relationships: Dict[NodeRelationship, Node]\n +excluded_embed_metadata_keys: List[str]\n +excluded_llm_metadata_keys: List[str]\n }\n \n class TextNode {\n +text: str\n +start_char_idx: Optional[int]\n +end_char_idx: Optional[int]\n }\n \n class Document {\n +text: str\n +doc_id: str\n +embedding: Optional[List[float]]\n }\n \n Node <|-- TextNode\n Node <|-- Document\n```\n\n## Document and Node Model\n\n### Document Structure\n\nDocuments represent the top-level container for source data. Each document contains metadata and can be broken down into smaller nodes for indexing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `doc_id` | `str` | Unique document identifier |\n| `text` | `str` | Full text content |\n| `metadata` | `Dict[str, Any]` | Associated metadata |\n| `embedding` | `Optional[List[float]]` | Pre-computed embedding |\n\n### Node Relationships\n\nNodes maintain relationships with other nodes through the `NodeRelationship` enum:\n\n| Relationship | Description |\n|--------------|-------------|\n| `SOURCE` | Parent document relationship |\n| `PREVIOUS` | Previous sibling node |\n| `NEXT` | Next sibling node |\n| `PARENT` | Parent node in hierarchy |\n| `CHILD` | Child node in hierarchy |\n\n资料来源：[llama-index-core/llama_index/core/node_parser/node.py:30-80]()\n\n## Storage Architecture\n\n### Storage Context\n\nThe `StorageContext` manages persistence layers for various data components:\n\n```mermaid\ngraph TD\n StorageContext --> VectorStore\n StorageContext --> DocStore\n StorageContext --> IndexStore\n StorageContext --> GraphStore\n \n VectorStore --> Milvus[Milvus]\n VectorStore --> Chroma[Chroma]\n VectorStore --> Pinecone[Pinecone]\n \n DocStore --> MongoDB[MongoDB]\n DocStore --> Redis[Redis]\n DocStore --> Simple[SimpleKVStore]\n```\n\n资料来源：[llama-index-core/llama_index/core/storage/storage_context.py:1-50]()\n\n### Storage Components\n\n| Component | Purpose |\n|-----------|---------|\n| `vector_store` | Stores embedding vectors for similarity search |\n| `doc_store` | Stores serialized nodes and documents |\n| `index_store` | Stores index metadata and configurations |\n| `graph_store` | Stores knowledge graph relationships |\n\n## Index Architecture\n\n### Base Index Structure\n\nIndexes provide the mechanism for organizing and querying documents. The base index class establishes the contract for all index implementations:\n\n```mermaid\ngraph LR\n A[Documents] --> B[Index Construction]\n B --> C[Node Parsing]\n C --> D[Embedding Generation]\n D --> E[Vector Storage]\n E --> F[Queryable Index]\n```\n\n### Index Types\n\n| Index Type | Use Case |\n|------------|----------|\n| `VectorStoreIndex` | Semantic search over embeddings |\n| `SummaryIndex` | Document summarization |\n| `KeywordTableIndex` | Keyword-based retrieval |\n| `KnowledgeGraphIndex` | Graph-based knowledge representation |\n\n资料来源：[llama-index-core/llama_index/core/indices/base.py:1-80]()\n\n## Query Engine Architecture\n\n### Query Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant QueryEngine\n participant Retriever\n participant LLM\n participant Response\n \n User->>QueryEngine: Query Request\n QueryEngine->>Retriever: Retrieve Nodes\n Retriever-->>QueryEngine: Source Nodes\n QueryEngine->>LLM: Synthesize Response\n LLM-->>QueryEngine: Response\n QueryEngine->>Response: Format Output\n Response-->>User: Formatted Answer\n```\n\n### Retriever Types\n\n| Retriever | Description |\n|-----------|-------------|\n| `VectorRetriever` | Embedding-based similarity search |\n| `KeywordRetriever` | BM25 or keyword matching |\n| `HybridRetriever` | Combined vector and keyword search |\n| `SentenceWindowRetriever` | Contextual window retrieval |\n\n## Configuration and Extensibility\n\n### Service Context\n\nThe `ServiceContext` bundles together the core service components:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `llm` | `LLM` | `OpenAI()` | Language model instance |\n| `embed_model` | `Embedding` | `OpenAIEmbedding()` | Embedding model instance |\n| `node_parser` | `NodeParser` | `SentenceSplitter()` | Text chunking strategy |\n| `prompt_helper` | `PromptHelper` | Auto-calculated | Prompt size optimization |\n\n### Customization Patterns\n\n```mermaid\ngraph TD\n subgraph \"Extension Points\"\n CustomLLM[Custom LLM Implementation]\n CustomEmbed[Custom Embedding Model]\n CustomParser[Custom Node Parser]\n CustomStore[Custom Storage Backend]\n end\n \n CustomLLM -->|inherits| LLMBase[LLM Base]\n CustomEmbed -->|inherits| EmbedBase[Embedding Base]\n CustomParser -->|inherits| NodeParserBase[NodeParser Base]\n CustomStore -->|inherits| StorageContextBase[StorageContext Base]\n```\n\n## Summary\n\nThe Core Architecture of LlamaIndex establishes a modular, extensible framework built on well-defined abstractions. The layered architecture—from base interfaces like `LLM` and `Embedding` through storage and indexing components to application-layer query engines—enables developers to:\n\n1. **Swap implementations** without changing application code\n2. **Extend functionality** through inheritance and composition\n3. **Maintain clean separation** between concerns\n4. **Support multiple providers** through unified interfaces\n\nThe architecture follows consistent patterns across components, making the framework predictable and learnable while supporting the diverse requirements of production LLM applications.\n\n---\n\n## See Also\n\n- [LLM Integrations](../llms/README.md)\n- [Embedding Integrations](../embeddings/README.md)\n- [Index Examples](../examples/index.md)\n- [Storage Integrations](../storage/README.md)\n\n---\n\n\n\n## Integration Architecture\n\n### 相关页面\n\n相关主题：[Core Architecture](#core-architecture), [Retrieval and Reranking](#retrieval-reranking)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-integrations/readers/llama-index-readers-preprocess/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-preprocess/README.md)\n- [llama-index-integrations/readers/llama-index-readers-remote-depth/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/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/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- [llama-index-integrations/llms/llama-index-llms-lmstudio/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-lmstudio/README.md)\n- [llama-index-integrations/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n- [llama-index-integrations/llms/llama-index-llms-langchain/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-langchain/README.md)\n \n\n# Integration Architecture\n\n## Overview\n\nLlamaIndex employs a modular integration architecture that extends the core framework's capabilities through a comprehensive ecosystem of pluggable components. The integration system allows developers to connect LlamaIndex with external services, APIs, local models, and specialized tools without modifying the core library. This architecture follows a provider-based pattern where each integration package implements standardized interfaces to ensure compatibility and consistent behavior across different external systems.\n\nThe integration architecture serves as the bridge between LlamaIndex's core data structures and the diverse landscape of LLM providers, embedding services, document loaders, and auxiliary tools. By maintaining well-defined contracts between components, the system enables seamless swapping of implementations while preserving the overall workflow of building retrieval-augmented generation (RAG) pipelines and query engines.\n\n## Integration Categories\n\nLlamaIndex organizes its integrations into distinct categories, each addressing a specific aspect of the LLM application development workflow. The categorization ensures logical separation of concerns and simplifies dependency management for end users.\n\n### LLM Integrations\n\nLLM (Large Language Model) integrations provide adapters for connecting to various language model providers. These integrations implement the unified LLM interface defined in `llama_index.core.llms`, allowing developers to switch between providers without changing application code. Each LLM integration handles provider-specific authentication, request formatting, response parsing, and streaming behavior.\n\n| Integration Package | Provider | Key Features |\n|---------------------|----------|--------------|\n| `llama-index-llms-contextual` | Contextual | Contextual LLM wrapper |\n| `llama-index-llms-konko` | Konko | Supports both Konko and OpenAI models |\n| `llama-index-llms-lmstudio` | LM Studio | Local server integration |\n| `llama-index-llms-monsterapi` | MonsterAPI | Private deployments and GA models |\n| `llama-index-llms-modelscope` | ModelScope | Qwen and other ModelScope models |\n| `llama-index-llms-langchain` | LangChain | LangChain LLM wrapper |\n| `llama-index-llms-optimum-intel` | Intel Optimum | CPU-optimized inference |\n\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\n### Reader Integrations\n\nReader integrations enable data ingestion from various document sources and web content. These loaders transform external data formats into LlamaIndex's internal `Document` schema, providing a unified representation regardless of the source type.\n\n| Reader Type | Source Format | Package |\n|-------------|---------------|---------|\n| Document Readers | PDF, DOCX, HTML | `llama-index-readers-docling` |\n| Web Readers | URLs, Articles | `llama-index-readers-web` |\n| Wikipedia | Wikipedia pages | `llama-index-readers-wikipedia` |\n| Remote Content | Deep link crawling | `llama-index-readers-remote-depth` |\n| Cloud Storage | Box files | `llama-index-readers-box` |\n| Preprocessed | Chunks from Preprocess API | `llama-index-readers-preprocess` |\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-wikipedia/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-wikipedia/README.md)\n\n### Embedding Integrations\n\nEmbedding integrations provide vectorization capabilities through external embedding models. These components convert text into dense vector representations suitable for semantic search and similarity operations.\n\n| Provider | Model Examples | Package |\n|----------|---------------|---------|\n| Ollama | `nomic-embed-text`, `embeddinggemma`, `mxbai-embed-large` | `llama-index-embeddings-ollama` |\n\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### Index Integrations\n\nIndex integrations connect to managed vector search services, providing fully-hosted indexing and retrieval capabilities. These integrations abstract the complexity of distributed vector databases behind LlamaIndex's retriever interface.\n\n| Managed Service | Package | Features |\n|-----------------|---------|----------|\n| Vectara | `llama-index-indices-managed-vectara` | RAG pipeline, retriever, query engine |\n\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\n### Tool Integrations\n\nTool integrations extend LlamaIndex's agent capabilities by providing access to external services that can be invoked during agent execution.\n\n| Tool Provider | Features | Package |\n|---------------|----------|---------|\n| Moss | Hybrid search (keyword + semantic) | `llama-index-tools-moss` |\n\n### Callback Integrations\n\nCallback integrations enable observability and feedback collection by integrating with external monitoring and evaluation platforms.\n\n| Platform | Purpose | Package |\n|----------|---------|---------|\n| Argilla | Feedback loop, LLM monitoring | `llama-index-callbacks-argilla` |\n\n资料来源：[llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/callbacks/llama-index-callbacks-argilla/README.md)\n\n## System Architecture\n\nThe integration architecture follows a layered approach where core abstractions define the contracts, and integration packages provide concrete implementations. This design enables horizontal scalability of integrations while maintaining vertical consistency with the core framework.\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[Core LlamaIndex]\n B --> C[Interface Abstractions]\n C --> D[LLM Abstraction]\n C --> E[Reader Abstraction]\n C --> F[Embedding Abstraction]\n C --> G[Retriever Abstraction]\n D --> H[LLM Integrations]\n E --> I[Reader Integrations]\n F --> J[Embedding Integrations]\n G --> K[Index Integrations]\n H --> L[Konko, LMStudio, MonsterAPI, etc.]\n I --> M[Docling, Wikipedia, Web, Box, etc.]\n J --> N[Ollama Embeddings]\n K --> O[Vectara]\n```\n\n## Common Integration Patterns\n\n### LLM Integration Pattern\n\nLLM integrations follow a consistent initialization pattern that accepts provider-specific configuration parameters. The typical constructor accepts a model identifier, base URL for API endpoints, and optional generation parameters such as temperature and maximum tokens.\n\n```python\nfrom llama_index.llms.provider_name import ProviderLLM\n\nllm = ProviderLLM(\n model=\"model-identifier\",\n api_key=\"your-api-key\",\n temperature=0.7,\n max_tokens=256\n)\n```\n\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### Reader Integration Pattern\n\nReader integrations follow a loader pattern where initialization may require credentials, and the `load_data` method accepts source-specific parameters such as URLs, file paths, or query filters.\n\n```python\nfrom llama_index.readers.source_type import SourceReader\n\nreader = SourceReader(credentials=\"your-credentials\")\ndocuments = reader.load_data(source=\"document-source\")\n```\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-remote-depth/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-remote-depth/README.md)\n\n## Data Flow Architecture\n\nThe integration architecture enables a complete RAG pipeline where each component plays a specific role in transforming input data into actionable insights.\n\n```mermaid\ngraph LR\n A[Document Sources] --> B[Readers]\n B --> C[Documents]\n C --> D[Node Parsers]\n D --> E[Nodes]\n E --> F[Vector Index]\n E --> G[Storage Context]\n F --> H[Retriever]\n G --> H\n H --> I[Query Engine]\n I --> J[LLM]\n J --> K[Response]\n```\n\n## Installation and Dependency Management\n\nEach integration package follows the naming convention `llama-index-{category}-{provider}` and can be installed independently via pip. This modular approach minimizes dependency overhead by allowing users to install only the packages required for their specific use case.\n\n| Category | Package Naming Pattern | Installation Command |\n|----------|----------------------|---------------------|\n| LLM | `llama-index-llms-{provider}` | `pip install llama-index-llms-{provider}` |\n| Reader | `llama-index-readers-{source}` | `pip install llama-index-readers-{source}` |\n| Embedding | `llama-index-embeddings-{provider}` | `pip install llama-index-embeddings-{provider}` |\n| Index | `llama-index-indices-{type}-{provider}` | `pip install llama-index-indices-{type}-{provider}` |\n| Tool | `llama-index-tools-{provider}` | `pip install llama-index-tools-{provider}` |\n| Callback | `llama-index-callbacks-{platform}` | `pip install llama-index-callbacks-{platform}` |\n\n## Configuration Management\n\nIntegrations typically support configuration through both constructor parameters and environment variables. This dual approach accommodates both explicit configuration in code and secret management through environment-based configuration.\n\n### Environment Variable Pattern\n\nMany integrations follow a pattern where API keys can be set as environment variables for security and convenience:\n\n```bash\nexport PROVIDER_API_KEY=\"your-api-key\"\nexport OPENAI_API_KEY=\"your-openai-key\"\n```\n\n### Constructor Parameter Pattern\n\nAlternatively, credentials can be passed directly to the integration constructor:\n\n```python\nllm = ProviderLLM(\n model=\"model-name\",\n api_key=\"explicit-api-key\",\n base_url=\"https://api.provider.com\"\n)\n```\n\n资料来源：[llama-index-integrations/llms/llama-index-llms-lmstudio/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-lmstudio/README.md)\n\n## Extending the Architecture\n\nThe integration architecture is designed for extensibility. New integrations can be created by implementing the appropriate abstract base classes defined in `llama_index.core`. Each integration category has its own interface specification that ensures consistency across implementations.\n\n### Creating a New LLM Integration\n\nTo create a new LLM integration, implement the following interface contract:\n\n1. Inherit from the base LLM class\n2. Implement `complete()`, `chat()`, and streaming methods\n3. Handle provider-specific authentication and error handling\n4. Follow the naming convention for the package\n\n### Creating a New Reader Integration\n\nTo create a new reader integration:\n\n1. Implement a loader class with `load_data()` method\n2. Transform source data into `Document` objects\n3. Handle pagination, filtering, and error cases appropriately\n4. Document supported source formats and parameters\n\n## Integration Testing Considerations\n\nEach integration package maintains its own test suite to verify compatibility with the external service. Integration tests typically require actual API credentials and network access, distinguishing them from unit tests that mock external dependencies.\n\n## Best Practices\n\nWhen working with LlamaIndex integrations, consider the following best practices:\n\n1. **Dependency Isolation**: Install only required integration packages to minimize potential conflicts\n2. **Credential Management**: Use environment variables for sensitive credentials in production\n3. **Error Handling**: Implement appropriate retry logic and fallback strategies for external service calls\n4. **Resource Management**: Close connections and release resources properly when using streaming responses\n5. **Version Compatibility**: Check integration package versions against the core LlamaIndex version for compatibility\n\n## Deprecated Integrations\n\nSome integration packages may be discontinued over time as external services evolve or change their offerings. When an integration is deprecated, it will receive no further updates or support. Users should migrate to alternative solutions before removing deprecated packages from their projects.\n\n资料来源：[llama-index-integrations/readers/llama-index-readers-preprocess/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-preprocess/README.md)\n\n## Conclusion\n\nThe integration architecture provides a flexible, extensible framework for connecting LlamaIndex with the broader ecosystem of LLM providers, data sources, and tools. By maintaining standardized interfaces while allowing provider-specific implementations, the architecture enables developers to build sophisticated RAG applications without being locked into a single vendor or service. The modular design supports incremental adoption, allowing teams to integrate new capabilities as their requirements evolve.\n\n---\n\n\n\n## Documents and Nodes\n\n### 相关页面\n\n相关主题：[Storage Systems](#storage-systems), [Query Engines](#query-engines)\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/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/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/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-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/node_parser/llama-index-node-parser-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/node_parser/llama-index-node-parser-docling/README.md)\n \n\n# Documents and Nodes\n\n## Overview\n\nIn LlamaIndex, **Documents** and **Nodes** are the fundamental data structures that represent information to be indexed, searched, and retrieved. Documents serve as the primary unit of input data, while Nodes are the granular chunks created during document processing for optimal embedding and retrieval.\n\n## Document Model\n\n### Purpose and Scope\n\nA Document in LlamaIndex represents a single unit of data to be indexed. It encapsulates the content along with associated metadata that provides context about the source, type, and additional information useful for retrieval and processing.\n\n### Core Document Schema\n\nThe Document model is defined in `llama-index-core/llama_index/core/schema.py` and includes the following key attributes:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `text` | str | The main text content of the document |\n| `id_` | str | Unique identifier for the document |\n| `metadata` | Dict[str, Any] | Additional metadata about the document |\n| `mimetype` | str | MIME type of the document content |\n| `relationships` | Dict[str, RelationshipType] | Relationships to other nodes/documents |\n\n### Document Construction\n\nDocuments can be created with varying levels of detail:\n\n```python\nfrom llama_index.core import Document\n\n# Basic document\ndoc = Document(text=\"Your content here\")\n\n# Document with metadata\ndoc = Document(\n text=\"Your content here\",\n metadata={\n \"source\": \"review.txt\",\n \"author\": \"John Doe\",\n \"date\": \"2024-01-15\"\n }\n)\n```\n\n## Node Model\n\n### Purpose and Scope\n\nNodes are the result of parsing and chunking Documents into smaller, semantically coherent pieces. Each Node inherits document-like properties but adds relationship information linking back to its parent Document and sibling Nodes.\n\n### Node Structure\n\nNodes extend the Document schema with additional attributes defined in `llama-index-core/llama_index/core/schema.py`:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `node_id` | str | Unique identifier for the node |\n| `start_char_idx` | int | Starting character index in parent document |\n| `end_char_idx` | int | Ending character index in parent document |\n| `text_template` | str | Template for rendering the node text |\n| `relationships` | Dict[RelationshipType, RelatedNodeType] | Relationships including PARENT, PREVIOUS, NEXT |\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[Raw Input Data] --> B[Document]\n B --> C[Node Parser]\n C --> D[Nodes]\n D --> E[Embedding Model]\n E --> F[Vector Index]\n \n G[Metadata] --> B\n H[Relationships] --> D\n \n B -->|PARENT| D\n D -->|CHILD| B\n```\n\n## Readers and Loading\n\n### Base Reader Interface\n\nReaders are responsible for loading data from various sources and converting them into Documents. The base reader interface is defined in `llama-index-core/llama_index/core/readers/base.py`.\n\n| Method | Description |\n|--------|-------------|\n| `load_data()` | Load documents from a data source |\n| `lazy_load_data()` | Lazily load documents for memory efficiency |\n\n### Supported Reader Types\n\nLlamaIndex provides numerous reader integrations for different data sources:\n\n| Category | Reader | Description |\n|----------|--------|-------------|\n| Document | Docling Reader | PDF, DOCX, HTML extraction to Markdown or JSON |\n| Document | MarkItDown Reader | Converts various formats to Markdown |\n| Document | Docugami Loader | XML knowledge graph from PDF/DOCX |\n| Web | NewsArticleReader | Parses news article URLs |\n| Web | UnstructuredURLLoader | URL text extraction via Unstructured.io |\n| Web | TrafilaturaWebReader | Web scraping with trafilatura |\n| Web | MainContentExtractorReader | Main content extraction from websites |\n| Web | ReadabilityWebPageReader | Readability-based web extraction |\n| Web | RemoteDepthReader | Recursive URL loading with depth control |\n| Web | WholeSiteReader | Full site scraping with prefix/depth |\n| Academic | SemanticScholarReader | Scholarly articles and papers |\n| Database | Chroma Reader | Loading from Chroma vector store |\n\n### Usage Example\n\n```python\nfrom llama_index.readers.docling import DoclingReader\n\nreader = DoclingReader()\ndocs = reader.load_data(file_path=\"document.pdf\")\n```\n\n## Node Parsers\n\n### Purpose and Scope\n\nNode Parsers transform Documents into Nodes by splitting content based on semantic boundaries. The interface is defined in `llama-index-core/llama_index/core/node_parser/interface.py`.\n\n### Core Interface Methods\n\n| Method | Description |\n|--------|-------------|\n| `get_nodes_from_documents()` | Parse documents into nodes |\n| `get_batch_nodes()` | Process documents in batches |\n\n### Sentence Splitter Parser\n\nThe sentence-based node parser in `llama-index-core/llama_index/core/node_parser/text/sentence.py` provides configurable text chunking:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `separator` | str | \"\\n\\n\" | Chunk separator |\n| `chunk_size` | int | 1024 | Maximum characters per chunk |\n| `chunk_overlap` | int | 0 | Overlap between chunks |\n| `chunking_tokenizer` | callable | None | Custom tokenizer function |\n| `callback_manager` | CallbackManager | None | Event callbacks |\n\n### Docling Node Parser\n\nThe Docling Node Parser (`llama-index-integrations/node_parser/llama-index-node-parser-docling/README.md`) parses Docling JSON output into LlamaIndex nodes with rich metadata:\n\n```python\nfrom llama_index.node_parser.docling import DoclingNodeParser\n\nnode_parser = DoclingNodeParser()\nnodes = node_parser.get_nodes_from_documents(documents=docs)\n```\n\n## Document-Node Relationships\n\n### Relationship Types\n\nNodes maintain typed relationships to other components:\n\n| Relationship | Description |\n|--------------|-------------|\n| `PARENT` | Link to parent Document |\n| `CHILD` | Link to child elements |\n| `PREVIOUS` | Previous sibling Node |\n| `NEXT` | Next sibling Node |\n| `SOURCE` | Source Document reference |\n\n### Metadata Preservation\n\nNodes automatically inherit and extend document metadata:\n\n```python\n# Node metadata includes provenance information\n{\n 'doc_items': [{'self_ref': '#/main-text/21'}],\n 'prov': [{'page_no': 2, 'bbox': {...}}],\n 'headings': ['2 Getting Started']\n}\n```\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Load Data] --> B[Create Document]\n B --> C[Parse Document]\n C --> D[Generate Nodes]\n D --> E[Create Embeddings]\n E --> F[Build Index]\n \n A1[Readers] --> A\n C1[Node Parsers] --> C\n```\n\n## Best Practices\n\n### Document Creation\n\n1. Always assign unique `id_` attributes for tracking\n2. Include comprehensive metadata for filtering\n3. Specify `mimetype` when content type matters\n\n### Node Parsing\n\n1. Choose appropriate `chunk_size` for your embedding model\n2. Configure `chunk_overlap` for context continuity\n3. Use semantic-aware parsers (Docling) for complex documents\n\n### Memory Management\n\n1. Use `lazy_load_data()` for large document collections\n2. Consider batch processing for node parsing\n3. Leverage streaming for very large files\n\n## Related Integrations\n\n| Integration | Use Case |\n|-------------|----------|\n| VectaraIndex | Managed semantic search |\n| ChromaReader | Vector database loading |\n| AlibabaCloud AISearch | Cloud-based document parsing |\n| Ollama Embeddings | Local embedding generation |\n\n## Summary\n\nDocuments serve as the primary data ingestion point in LlamaIndex, encapsulating raw content and metadata from various sources. Nodes are the processed, chunked representations optimized for embedding generation and retrieval. Together with Readers and Node Parsers, they form the foundation of the LlamaIndex data pipeline.\n\n---\n\n\n\n## Storage Systems\n\n### 相关页面\n\n相关主题：[Documents and Nodes](#documents-nodes), [Retrieval and Reranking](#retrieval-reranking)\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/storage/docstore/simple_docstore.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/simple_docstore.py)\n- [llama-index-core/llama_index/core/storage/index_store/simple_index_store.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/index_store/simple_index_store.py)\n- [llama-index-core/llama_index/core/storage/chat_store/simple_chat_store.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/chat_store/simple_chat_store.py)\n \n\n# Storage Systems\n\n## Overview\n\nLlamaIndex provides a comprehensive storage system that allows users to persist indexes, documents, and chat histories to disk for later retrieval and reuse. The storage architecture is built around the `StorageContext` class, which serves as the central coordinator for managing various storage backends including document stores, index stores, and chat stores.\n\nThe storage system enables:\n\n- **Persistence**: Save index data to disk for long-term storage\n- **Retrieval**: Reload previously persisted indexes without recomputation\n- **In-memory fallback**: Default in-memory storage when persistence is not configured\n- **Customizable backends**: Pluggable storage implementations for different use cases\n\n## Architecture\n\n```mermaid\ngraph TD\n A[StorageContext] --> B[VectorStore]\n A --> C[DocStore]\n A --> D[IndexStore]\n A --> E[ChatStore]\n A --> F[ImageStore]\n A --> G[GraphStore]\n \n C --> H[SimpleDocStore]\n C --> I[MongoDocStore]\n C --> J[KVDocStore]\n \n D --> K[SimpleIndexStore]\n D --> L[MongoIndexStore]\n D --> M[KVIndexStore]\n \n E --> N[SimpleChatStore]\n E --> O[MongoChatStore]\n```\n\n## StorageContext\n\nThe `StorageContext` class is the main entry point for configuring storage in LlamaIndex. It aggregates all storage components and provides methods for persistence and retrieval.\n\n### Initialization\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# Create with default in-memory stores\nstorage_context = StorageContext.from_defaults()\n\n# Create with persistence to disk\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\n\n# Load existing index from disk\nindex = load_index_from_storage(storage_context=storage_context)\n```\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `persist_dir` | `str` | `None` | Directory path for persistence |\n| `vector_store` | `BaseVectorStore` | `InMemoryVectorStore` | Vector storage backend |\n| `docstore` | `BaseDocstore` | `SimpleDocumentStore` | Document storage backend |\n| `index_store` | `BaseIndexStore` | `SimpleIndexStore` | Index metadata storage |\n| `graph_store` | `BaseGraphStore` | `None` | Knowledge graph storage |\n| `chat_store` | `BaseChatStore` | `SimpleChatStore` | Chat history storage |\n| `image_store` | `BaseImageStore` | `None` | Image storage backend |\n\n### Persistence Methods\n\n| Method | Description |\n|--------|-------------|\n| `persist(persist_dir, ...)` | Save all storage components to disk |\n| `from_defaults(**kwargs)` | Create context with default or specified settings |\n| `load_index_from_storage()` | Class method to load index from persisted storage |\n\n## Document Store\n\nThe document store manages the storage and retrieval of `BaseDocument` objects. LlamaIndex provides several document store implementations.\n\n### SimpleDocumentStore\n\nThe default in-memory document store backed by SQLite for persistence.\n\n```python\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\n\ndocstore = SimpleDocumentStore(\n persist_path=\"./docstore.json\",\n redis_host=\"localhost\",\n redis_port=6379,\n redis_password=None\n)\n```\n\n### Document Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_documents(documents, batch_size)` | Add documents to the store |\n| `get_document(doc_id)` | Retrieve a document by ID |\n| `delete(doc_id)` | Remove a document by ID |\n| `get_nodes(node_ids)` | Retrieve nodes by their IDs |\n| `get_all_nodes()` | Retrieve all nodes from the store |\n| `persist(persist_path)` | Persist the document store to disk |\n\n### Data Model\n\nDocuments are stored with the following structure:\n\n```python\nclass BaseDocument:\n id_: str # Unique identifier\n embedding: List[float] # Vector embedding\n metadata: Dict[str, Any] # User-defined metadata\n text: str # Document text content\n excluded_embed_metadata_keys: List[str]\n excluded_llm_metadata_keys: List[str]\n relationships: Dict[DocumentRelationship, str]\n hash: str # Computed hash for caching\n __class__: type # Document type (optional)\n```\n\n## Index Store\n\nThe index store manages index metadata and structure, enabling efficient retrieval of index components.\n\n### SimpleIndexStore\n\nThe default index store implementation using JSON file storage.\n\n```python\nfrom llama_index.core.storage.index_store import SimpleIndexStore\n\nindex_store = SimpleIndexStore(\n persist_path=\"./index_store.json\"\n)\n```\n\n### Index Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_index_struct(index_struct)` | Store an index structure |\n| `get_index_struct(struct_id)` | Retrieve index structure by ID |\n| `get_index_structs()` | List all stored index structures |\n| `delete_index_struct(struct_id)` | Remove an index structure |\n\n### Supported Index Types\n\n| Index Type | Description |\n|------------|-------------|\n| `VectorStoreIndex` | Dense vector-based retrieval |\n| `SummaryIndex` | Summary-based indexing |\n| `KeywordTableIndex` | Keyword-based retrieval |\n| `KnowledgeGraphIndex` | Graph-based knowledge indexing |\n\n## Chat Store\n\nThe chat store manages conversation history for multi-turn interactions with language models.\n\n### SimpleChatStore\n\nA persistent chat store implementation for storing and retrieving chat messages.\n\n```python\nfrom llama_index.core.storage.chat_store import SimpleChatStore\n\nchat_store = SimpleChatStore(\n persist_path=\"./chat_store.json\"\n)\n```\n\n### Chat Store API\n\n| Method | Description |\n|--------|-------------|\n| `add_message(chat_id, message, role)` | Append a message to a chat session |\n| `get_messages(chat_id)` | Retrieve all messages for a chat |\n| `get_chat(chat_id)` | Get chat session details |\n| `delete_chat(chat_id)` | Remove a chat session |\n| `persist(persist_path)` | Save chat history to disk |\n\n### Message Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Message role (user/assistant/system) |\n| `content` | `str` | Message text content |\n| `additional_kwargs` | `Dict` | Extra metadata for the message |\n\n## Storage Workflow\n\n```mermaid\ngraph LR\n A[Create Documents] --> B[Initialize StorageContext]\n B --> C{Configure Backends}\n C --> D[In-Memory]\n C --> E[Persistent]\n D --> F[Build Index]\n E --> F\n F --> G[Index Created]\n G --> H[Persist to Disk]\n H --> I[StorageContext.persist]\n \n J[Load Index] --> K[load_index_from_storage]\n K --> L[Index Ready]\n```\n\n## Usage Examples\n\n### Basic Persistence\n\n```python\nfrom llama_index.core import VectorStoreIndex, StorageContext\n\n# Create documents\ndocuments = [...]\n\n# Create index with storage context\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\nindex = VectorStoreIndex.from_documents(\n documents, \n storage_context=storage_context\n)\n\n# Explicitly persist (optional - also happens on garbage collection)\nindex.storage_context.persist()\n```\n\n### Loading Persisted Index\n\n```python\nfrom llama_index.core import StorageContext, load_index_from_storage\n\n# Rebuild storage context from disk\nstorage_context = StorageContext.from_defaults(persist_dir=\"./storage\")\n\n# Load existing index\nindex = load_index_from_storage(storage_context=storage_context)\n\n# Query the loaded index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"Your question here\")\n```\n\n### Custom Storage Configuration\n\n```python\nfrom llama_index.core import StorageContext\nfrom llama_index.core.storage.docstore import SimpleDocumentStore\nfrom llama_index.core.storage.index_store import SimpleIndexStore\n\n# Create custom stores\ndocstore = SimpleDocumentStore(persist_path=\"./custom_docstore.json\")\nindex_store = SimpleIndexStore(persist_path=\"./custom_index_store.json\")\n\n# Configure storage context with custom stores\nstorage_context = StorageContext(\n docstore=docstore,\n index_store=index_store,\n persist_dir=\"./custom_storage\"\n)\n\n# Use with index\nindex = VectorStoreIndex.from_documents(\n documents,\n storage_context=storage_context\n)\n```\n\n## Storage Backend Comparison\n\n| Backend | Persistence | Performance | Scalability | Use Case |\n|---------|-------------|-------------|-------------|----------|\n| `SimpleDocumentStore` | JSON/SQLite | Medium | Low-Medium | Development, small datasets |\n| `RedisDocumentStore` | Redis | High | High | Production, distributed systems |\n| `MongoDocumentStore` | MongoDB | High | Very High | Large-scale deployments |\n| `KVDocumentStore` | Key-Value | High | Medium-High | General purpose |\n\n## Best Practices\n\n1. **Always specify unique document IDs**: Prevents duplicate entries and enables predictable retrieval\n ```python\n Document(id_=\"unique_doc_1\", text=\"content\")\n ```\n\n2. **Configure persistence early**: Set up storage context before building indexes to avoid data loss\n\n3. **Use appropriate batch sizes**: When adding many documents, use batch operations for better performance\n\n4. **Handle persistence errors**: Wrap persistence calls in try-except blocks for robustness\n\n5. **Backup important data**: Regularly backup persisted storage directories\n\n## Related Components\n\n- **Vector Stores**: Manage embedding vectors for semantic search\n- **Graph Stores**: Handle knowledge graph data structures\n- **Image Stores**: Store image data for multimodal applications\n- **Query Engines**: Use storage to retrieve relevant documents for queries\n- **Retrievers**: Access stored data for retrieval-augmented generation\n\n---\n\n\n\n## Query Engines\n\n### 相关页面\n\n相关主题：[Retrieval and Reranking](#retrieval-reranking), [Documents and Nodes](#documents-nodes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/query_engine/sub_question_query_engine.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/sub_question_query_engine.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- [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/query_engine/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/__init__.py)\n \n\n# Query Engines\n\nQuery Engines are the core components in LlamaIndex responsible for processing user queries and returning relevant responses by retrieving, synthesizing, and formatting information from indexed data.\n\n## Overview\n\nQuery Engines serve as the primary interface for querying indexed documents in LlamaIndex. They coordinate the retrieval of relevant context from the index and synthesize this information into coherent, helpful responses using Large Language Models (LLMs).\n\n**Key Responsibilities:**\n\n- Receive user queries and transform them into retrieval operations\n- Coordinate with retrievers to fetch relevant documents or data chunks\n- Route queries to appropriate response synthesizers\n- Handle query-time configuration such as similarity thresholds and response modes\n\n资料来源：[llama-index-core/llama_index/core/query_engine/__init__.py]()\n\n## Architecture\n\nThe query engine architecture follows a modular pipeline pattern where different components handle specific stages of query processing.\n\n```mermaid\ngraph TD\n A[User Query] --> B[Query Engine]\n B --> C[Retriever]\n C --> D[Node Postprocessor]\n D --> E[Response Synthesizer]\n E --> F[LLM]\n F --> G[Response]\n \n H[Vector Store Index] --> C\n I[Summary Index] --> C\n J[Knowledge Graph Index] --> C\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| BaseQueryEngine | Abstract base class defining the query interface | `llama_index.core.query_engine` |\n| RetrieverQueryEngine | Default query engine using retrievers | `retriever_query_engine.py` |\n| SubQuestionQueryEngine | Decomposes complex queries into sub-questions | `sub_question_query_engine.py` |\n| ResponseSynthesizer | Generates responses from retrieved context | `llama_index.core.response_synthesizers` |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py]()\n\n## RetrieverQueryEngine\n\nThe `RetrieverQueryEngine` is the default query engine implementation that combines retrieval with response synthesis.\n\n### Initialization\n\n```python\nfrom llama_index.core import VectorStoreIndex\n\nindex = VectorStoreIndex.from_documents(documents)\nquery_engine = index.as_query_engine()\n```\n\n### Constructor Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| retriever | BaseRetriever | Required | The retriever used to fetch relevant nodes |\n| response_synthesizer | BaseSynthesizer | None | Synthesizer for generating responses |\n| node_postprocessors | List[BaseNodePostprocessor] | [] | Post-processors applied after retrieval |\n| callback_manager | CallbackManager | None | Manages callbacks for query events |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py:40-60]()\n\n### Query Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant QueryEngine\n participant Retriever\n participant Postprocessor\n participant Synthesizer\n participant LLM\n \n User->>QueryEngine: query(question)\n QueryEngine->>Retriever: retrieve(query_str)\n Retriever-->>QueryEngine: nodes[]\n QueryEngine->>Postprocessor: postprocess(nodes)\n Postprocessor-->>QueryEngine: filtered_nodes[]\n QueryEngine->>Synthesizer: synthesize(query_str, nodes)\n Synthesizer->>LLM: generate(prompt)\n LLM-->>Synthesizer: response\n Synthesizer-->>QueryEngine: Response\n QueryEngine-->>User: Response\n```\n\n## SubQuestionQueryEngine\n\nThe `SubQuestionQueryEngine` handles complex queries by decomposing them into simpler sub-questions that can be answered independently.\n\n### Use Cases\n\n- Queries requiring information from multiple data sources\n- Complex questions that benefit from step-by-step reasoning\n- Multi-hop questions requiring logical deduction\n\n### Configuration\n\n```python\nfrom llama_index.core.query_engine import SubQuestionQueryEngine\nfrom llama_index.core.callbacks import CallbackManager\n\nquery_engine = SubQuestionQueryEngine.from_defaults(\n query_engine_tools=query_engine_tools,\n callback_manager=CallbackManager([callback]),\n verbose=True\n)\n```\n\n### Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| query_engine_tools | List[QueryEngineTool] | Required | List of query engines and their descriptions |\n| response_synthesizer | BaseSynthesizer | None | Response synthesizer to use |\n| sub_question_name | str | \"sub_question\" | Name for sub-question events |\n| parent_name | str | \"parent_question\" | Name for parent question events |\n| callback_manager | CallbackManager | None | Callback manager for events |\n| verbose | bool | False | Enable verbose output |\n\n资料来源：[llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py:50-80]()\n\n## Response Synthesizers\n\nResponse Synthesizers transform retrieved context into natural language responses.\n\n### Available Synthesizer Types\n\n| Synthesizer | Description | Use Case |\n|-------------|-------------|----------|\n| CompactAndRefine | Compacts retrieved context before generating | Large retrieval results |\n| TreeSummarize | Hierarchically summarizes retrieved nodes | Comprehensive responses |\n| SimpleSummarize | Direct concatenation and summarization | Quick, simple responses |\n| Refine | Iteratively improves response quality | High-quality refinement |\n| Accumulate | Combines responses from multiple sources | Multi-source queries |\n| Generation | Direct LLM generation from context | Simple generation tasks |\n\n### Base Interface\n\n```python\nclass BaseSynthesizer(ABC):\n @abstractmethod\n async def synthesize(\n self,\n query: QueryBundle,\n nodes: List[NodeWithScore],\n **kwargs: Any\n ) -> Response:\n pass\n```\n\n资料来源：[llama-index-core/llama_index/core/response_synthesizers/base.py:30-50]()\n\n## Vector Store Index Query Engine\n\nThe `VectorStoreIndex` provides built-in query engine creation through the `as_query_engine()` method.\n\n### Factory Method Parameters\n\n```python\nindex.as_query_engine(\n query_mode: str = \"default\",\n similarity_top_k: int = 10,\n vector_store_query_mode: str = \"default\",\n alpha: Optional[float] = None,\n **kwargs: Any\n) -> BaseQueryEngine\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| query_mode | str | \"default\" | Query execution mode |\n| similarity_top_k | int | 10 | Number of top results to retrieve |\n| vector_store_query_mode | str | \"default\" | Vector store specific query mode |\n| alpha | float | None | Hybrid search weight (0-1, default 0.5) |\n\n资料来源：[llama-index-core/llama_index/core/indices/vector_store/base.py]()\n\n### Query Modes\n\n| Mode | Description |\n|------|-------------|\n| `default` | Standard retrieval based on similarity |\n| `mmr` | Maximum Marginal Relevance for diverse results |\n| `hybrid` | Combines sparse and dense retrieval |\n\n## Query Engine Tool\n\nFor agent-based workflows, query engines can be wrapped as tools using the `QueryEngineTool` class.\n\n```python\nfrom llama_index.core.tools import QueryEngineTool\n\ntool = QueryEngineTool(\n query_engine=query_engine,\n metadata=ToolMetadata(\n name=\"website_index\",\n description=\"Useful for answering questions about text on websites\",\n )\n)\n```\n\n资料来源：[llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py:100-120]()\n\n## Advanced Configuration\n\n### Node Post-processors\n\nPost-processors filter and enhance retrieved nodes before synthesis.\n\n```python\nfrom llama_index.core.postprocessor import SimilarityPostprocessor\n\nquery_engine = index.as_query_engine(\n node_postprocessors=[\n SimilarityPostprocessor(similarity_cutoff=0.7)\n ]\n)\n```\n\n### Custom Query Engines\n\nCreate custom query engines by extending the base class:\n\n```python\nfrom llama_index.core.query_engine import BaseQueryEngine\n\nclass CustomQueryEngine(BaseQueryEngine):\n def __init__(self, retriever, synthesizer):\n self._retriever = retriever\n self._synthesizer = synthesizer\n \n async def _aquery(self, query_bundle: QueryBundle) -> Response:\n nodes = await self._retriever.aretrieve(query_bundle)\n response = await self._synthesizer.synthesize(\n query_bundle, nodes\n )\n return response\n```\n\n## Async Query Execution\n\nQuery engines support both sync and async execution patterns:\n\n```python\n# Synchronous\nresponse = query_engine.query(\"What is LlamaIndex?\")\n\n# Asynchronous\nresponse = await query_engine.aquery(\"What is LlamaIndex?\")\n```\n\n## Integration with Vector Indices\n\nQuery engines integrate with various index types:\n\n| Index Type | Default Query Engine | Features |\n|------------|---------------------|----------|\n| VectorStoreIndex | RetrieverQueryEngine | Semantic similarity search |\n| SummaryIndex | RetrieverQueryEngine | Full document retrieval |\n| KnowledgeGraphIndex | RetrieverQueryEngine | Graph-based traversal |\n| ComposableGraph | SubQuestionQueryEngine | Multi-index queries |\n\n## Best Practices\n\n1. **Choose appropriate top_k**: Balance between response quality and speed (typically 3-10 for most use cases)\n\n2. **Use sub-question engine for complex queries**: When queries require reasoning across multiple sources\n\n3. **Configure similarity thresholds**: Filter low-quality matches using post-processors\n\n4. **Enable callbacks for debugging**: Monitor query execution flow and performance\n\n5. **Select appropriate synthesizers**: Match the synthesizer type to your response quality requirements\n\n## Summary\n\nQuery Engines in LlamaIndex provide a flexible, extensible framework for retrieving and synthesizing information from indexed data. The modular architecture allows for customization at every stage of the query pipeline, from retrieval configuration to response generation.\n\n**Key Takeaways:**\n\n- Query engines orchestrate the retrieval-synthesis pipeline\n- `RetrieverQueryEngine` handles standard query flows\n- `SubQuestionQueryEngine` decomposes complex queries\n- Response synthesizers generate final output from context\n- Extensive configuration options enable fine-tuned control\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/response_synthesizers/base.py]()\n资料来源：[llama-index-core/llama_index/core/indices/vector_store/base.py]()\n\n---\n\n\n\n## Retrieval and Reranking\n\n### 相关页面\n\n相关主题：[Query Engines](#query-engines), [Storage Systems](#storage-systems)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/retrievers/recursive_retriever.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/retrievers/recursive_retriever.py)\n- [llama-index-core/llama_index/core/postprocessor/llm_rerank.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/llm_rerank.py)\n- [llama-index-core/llama_index/core/postprocessor/node.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/node.py)\n- [llama-index-core/llama_index/core/indices/property_graph/retriever.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/property_graph/retriever.py)\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/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md)\n \n\n# Retrieval and Reranking\n\n## Overview\n\nRetrieval and Reranking are fundamental components in LlamaIndex's architecture for building effective Retrieval-Augmented Generation (RAG) systems. The retrieval system identifies relevant context from various data sources, while the reranking system reorders retrieved results to optimize relevance using advanced techniques like LLM-based scoring.\n\nIn LlamaIndex, retrieval is handled through a flexible retriever abstraction that supports multiple retrieval strategies including vector-based search, keyword search, and hybrid approaches. Reranking serves as a post-processing step that improves result quality by reordering retrieved nodes based on more sophisticated relevance criteria.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Retrieval Phase]\n B --> C[Vector/Knowledge Graph Retrieval]\n C --> D[Initial Node Set]\n D --> E[Reranking Phase]\n E --> F[LLM Reranker]\n F --> G[Reordered Results]\n G --> H[Response Generation]\n \n I[Document Sources] --> J[Indexing]\n J --> K[Vector Store / Graph Store]\n K --> C\n```\n\n## Retrieval Components\n\n### Retriever Abstraction\n\nLlamaIndex provides a base `BaseRetriever` class that defines the interface for all retrieval implementations. Retrievers work in conjunction with indices to fetch relevant nodes from vector stores or knowledge graphs.\n\n**Core Retriever Classes:**\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| `BaseRetriever` | `llama-index-core/llama_index/core/retrievers/` | Abstract base for all retrievers |\n| `RecursiveRetriever` | `llama-index-core/llama_index/core/retrievers/recursive_retriever.py` | Multi-level recursive retrieval |\n| `PropertyGraphRetriever` | `llama-index-core/llama_index/core/indices/property_graph/retriever.py` | Graph-based retrieval |\n\n### Recursive Retriever\n\nThe `RecursiveRetriever` enables multi-level, hierarchical retrieval across different data sources and node types. It supports recursive traversal of indices and can fetch related nodes across different retrieval strategies.\n\n**Key Features:**\n- Recursive node resolution across index hierarchies\n- Support for multiple retriever types in a chain\n- Handling of nested document structures\n\n**Source:** `llama-index-core/llama_index/core/retrievers/recursive_retriever.py`\n\n### Property Graph Retriever\n\nThe Property Graph Retriever leverages knowledge graphs for retrieval, enabling structured queries over entity-relationship data. This retriever is particularly effective for complex queries requiring relationship-aware context.\n\n**Capabilities:**\n- Graph traversal-based retrieval\n- Entity filtering and relationship queries\n- Support for hybrid graph + vector search\n\n**Source:** `llama-index-core/llama_index/core/indices/property_graph/retriever.py:1-100`\n\n## Reranking System\n\n### Purpose and Role\n\nReranking improves retrieval quality by reordering initially retrieved candidates using more sophisticated relevance models. After an initial retrieval pass identifies candidate nodes, rerankers evaluate and reorder these results to maximize relevance to the query.\n\n### LLM Reranker\n\nThe `LLMRerank` post-processor uses a Language Model to score and reorder retrieved nodes based on semantic relevance. This approach provides higher quality ranking compared to simple vector similarity.\n\n**Key Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `top_n` | `int` | `None` | Number of top results to return after reranking |\n| `choice_batch_size` | `int` | `10` | Batch size for LLM ranking choices |\n| `llm` | `BaseLLM` | `None` | Language model for scoring |\n| `verbose` | `bool` | `False` | Enable verbose output |\n\n**Source:** `llama-index-core/llama_index/core/postprocessor/llm_rerank.py`\n\n### Node Post-Processors\n\nThe `NodePostprocessor` class provides additional filtering and transformation capabilities for retrieved nodes. These processors operate on the node level and can apply various transformations before final output.\n\n**Common Post-Processing Operations:**\n- Duplicate removal\n- Similarity threshold filtering\n- Metadata-based filtering\n\n**Source:** `llama-index-core/llama_index/core/postprocessor/node.py`\n\n## Data Flow\n\n```mermaid\ngraph LR\n A[User Query] --> B[Vector Search]\n B --> C[Top-K Nodes]\n C --> D[Post-Processors]\n D --> E[LLM Reranker]\n E --> F[Reranked Nodes]\n F --> G[Context for LLM]\n \n H[Documents] --> I[Indexing Pipeline]\n I --> J[Embedding Model]\n J --> K[Vector Store]\n K --> B\n```\n\n## Integration with Data Loaders\n\nLlamaIndex's retrieval system integrates seamlessly with various data loaders that prepare documents for indexing and retrieval.\n\n### Supported Data Sources\n\n| Reader | Use Case | Integration |\n|--------|----------|-------------|\n| `DoclingReader` | PDF, DOCX, HTML | `llama-index-readers-docling` |\n| `SimpleWebPageReader` | Static websites | `llama-index-readers-web` |\n| `RemoteDepthReader` | Multi-level URL crawling | `llama-index-readers-remote-depth` |\n| `WikipediaReader` | Wikipedia articles | `llama-index-readers-wikipedia` |\n| `SemanticScholarReader` | Academic papers | `llama-index-readers-semanticscholar` |\n\n**Source:** `llama-index-integrations/readers/llama-index-readers-docling/README.md`\n\n### Document Processing Pipeline\n\nDocuments loaded through readers undergo the following processing:\n\n1. **Parsing** - Extract text content from various formats (PDF, DOCX, HTML)\n2. **Node Parsing** - Split documents into semantic chunks (nodes)\n3. **Embedding** - Generate vector embeddings for each node\n4. **Indexing** - Store nodes and embeddings in appropriate stores\n5. **Retrieval** - Fetch relevant nodes based on queries\n\n**Source:** `llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/simple_web/README.md`\n\n## Usage Patterns\n\n### Basic Retrieval with Reranking\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.core.postprocessor import LLMRerank\n\n# Load documents and create index\nindex = VectorStoreIndex.from_documents(documents)\n\n# Configure reranking\nreranker = LLMRerank(\n top_n=5,\n choice_batch_size=10\n)\n\n# Query with reranking\nquery_engine = index.as_query_engine(\n node_postprocessors=[reranker]\n)\n\nresponse = query_engine.query(\"Your question here\")\n```\n\n### Recursive Retrieval\n\n```python\nfrom llama_index.core.retrievers import RecursiveRetriever\n\n# Configure recursive retrieval across multiple levels\nrecursive_retriever = RecursiveRetriever(\n retriever_dict={\n \"root\": vector_retriever,\n \"documents\": document_retriever\n }\n)\n```\n\n## Configuration Options\n\n### Retrieval Configuration\n\n| Option | Description | Applies To |\n|--------|-------------|------------|\n| `similarity_top_k` | Number of initial candidates | Vector retrieval |\n| `retrieval_mode` | Vector, keyword, or hybrid | Hybrid search |\n| `node_postprocessors` | List of post-processing steps | All retrievers |\n\n### Reranking Configuration\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `top_n` | Final number of results | 5 |\n| `score_threshold` | Minimum relevance score | None |\n| `model` | Reranking model | gpt-3.5-turbo |\n\n## Advanced Topics\n\n### Hybrid Retrieval with Reranking\n\nCombining vector and keyword search with LLM reranking provides robust retrieval across diverse query types:\n\n1. **Vector Search** - Captures semantic similarity\n2. **Keyword Search** - Captures exact term matching\n3. **LLM Reranking** - Optimizes final ordering\n\n### Custom Retrievers\n\nDevelopers can create custom retrievers by extending `BaseRetriever`:\n\n```python\nfrom llama_index.core.retrievers import BaseRetriever\n\nclass CustomRetriever(BaseRetriever):\n def _retrieve(self, query_bundle):\n # Custom retrieval logic\n pass\n```\n\n## Summary\n\nRetrieval and Reranking in LlamaIndex form a two-phase system where initial retrieval identifies candidate nodes and reranking optimizes their ordering. The architecture supports multiple retrieval strategies (vector, graph, recursive) and leverages LLM-based reranking for improved result quality. Integration with various data loaders enables seamless indexing from diverse sources, while the post-processor abstraction allows flexible pipeline customization.\n\n---\n\n\n\n## Agent Framework\n\n### 相关页面\n\n相关主题：[Memory Systems](#memory-systems)\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# Agent Framework\n\n## Overview\n\nThe LlamaIndex Agent Framework provides a flexible, extensible system for building AI agents that can reason, plan, and execute actions using tools. The framework enables the creation of both single-agent and multi-agent systems capable of interacting with external data sources, performing complex reasoning tasks, and orchestrating workflows.\n\nAgents in LlamaIndex are designed to combine large language model (LLM) capabilities with structured tool usage, memory management, and workflow orchestration. The framework supports various agent types including ReAct (Reasoning + Acting) agents and workflow-based agents.\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:1-50]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User Query] --> B[Agent]\n B --> C[Reasoning Engine]\n C --> D[Tool System]\n D --> E[External Tools]\n C --> F[Memory]\n B --> G[Workflow Orchestrator]\n G --> H[Sub-Agents]\n H --> D\n```\n\nThe framework is built on several key components that work together to enable sophisticated agent behaviors:\n\n| Component | Purpose |\n|-----------|---------|\n| **Agent** | Core entity that processes queries and generates responses |\n| **Reasoning Engine** | Handles thought processes and decision making |\n| **Tool System** | Provides access to external functions and APIs |\n| **Memory** | Stores conversation history and intermediate results |\n| **Workflow Orchestrator** | Manages complex multi-step tasks |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:50-100]()\n\n## ReAct Agent\n\nThe ReAct (Synergizing Reasoning and Acting) agent implements a reasoning loop that combines thought processes with tool actions. This agent type is particularly effective for tasks requiring logical deduction and external information retrieval.\n\n### ReAct Formatter\n\nThe ReAct formatter is responsible for constructing prompts that guide the agent through the reasoning-action-observation cycle. It defines the structure of thoughts, actions, and observations in the agent's prompt.\n\n```mermaid\ngraph LR\n A[Thought] --> B[Action]\n B --> C[Observation]\n C --> A\n```\n\n#### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| `system_prompt` | Instructions for the agent's role and behavior |\n| `tool_prompt` | Description of available tools |\n| `formatter` | Defines the format for thoughts, actions, observations |\n| `examples` | Few-shot examples for better performance |\n\n资料来源：[llama-index-core/llama_index/core/agent/react/formatter.py:1-80]()\n\n### ReAct Output Parsing\n\nThe ReAct agent uses specialized output parsers to extract structured information from LLM responses:\n\n```python\nclass ReActOutputParser:\n def parse(self, output: str) -> ActionOutput:\n # Parse thought, action, and action input from output\n pass\n```\n\nThis parsing enables the agent to:\n1. Extract the reasoning thought process\n2. Identify the tool to invoke\n3. Extract the tool's input parameters\n4. Process the tool's output as an observation\n\n资料来源：[llama-index-core/llama_index/core/agent/react/formatter.py:80-150]()\n\n## Workflow-Based Agents\n\nWorkflow-based agents provide a more structured approach to agent execution, using state machines and defined steps to process queries.\n\n### Base Agent\n\nThe `BaseAgent` class provides the foundation for all agent implementations in the workflow system:\n\n```mermaid\ngraph TD\n A[Input] --> B[State Machine]\n B --> C{Step Execution}\n C -->|Step 1| D[Process Step]\n D --> E[Update State]\n E --> C\n C -->|Complete| F[Generate Response]\n```\n\n#### Base Agent API\n\n| Method | Description |\n|--------|-------------|\n| `run()` | Execute the agent with input |\n| `reset()` | Reset agent state |\n| `get_state()` | Retrieve current agent state |\n| `set_state()` | Set agent state |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:100-200]()\n\n### Agent State Management\n\nAgents maintain state throughout their execution, which includes:\n\n| State Component | Type | Purpose |\n|-----------------|------|---------|\n| `input` | str | Original user input |\n| `current_step` | int | Current execution step |\n| `memory` | Memory | Conversation history |\n| `context` | dict | Additional context data |\n| `steps` | List[Step] | Executed steps |\n| `output` | Any | Final output |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/base_agent.py:200-300]()\n\n## Tool System\n\nThe Tool System enables agents to interact with external resources and perform actions beyond text generation.\n\n### Function Tool\n\n`FunctionTool` provides a decorator-based interface for creating tools from Python functions:\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\n@FunctionTool.from_defaults\ndef search_database(query: str) -> str:\n \"\"\"Search the knowledge base for relevant information.\"\"\"\n # Implementation here\n return results\n```\n\n#### FunctionTool Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `fn` | Callable | Required | The function to wrap |\n| `name` | str | Function name | Tool identifier |\n| `description` | str | Function docstring | Tool description for LLM |\n| `fn_schema` | BaseModel | Auto-generated | Input schema |\n| `return_direct` | bool | False | Return raw output |\n\n资料来源：[llama-index-core/llama_index/core/tools/function_tool.py:1-100]()\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ToolRegistry\n participant FunctionTool\n participant External\n\n Agent->>ToolRegistry: Request tool by name\n ToolRegistry->>FunctionTool: Get tool instance\n FunctionTool->>External: Execute function\n External-->>FunctionTool: Return result\n FunctionTool-->>Agent: Format response\n```\n\n### Creating Custom Tools\n\nTools can be created using the `@FunctionTool.from_defaults` decorator:\n\n```python\n@FunctionTool.from_defaults(name=\"calculator\", description=\"Perform mathematical calculations\")\ndef calculate(expression: str) -> str:\n \"\"\"Evaluate a mathematical expression.\"\"\"\n return str(eval(expression))\n```\n\nOr programmatically:\n\n```python\nfrom llama_index.core.tools import FunctionTool\n\ndef my_function(arg1: str, arg2: int) -> str:\n return f\"{arg1} repeated {arg2} times\"\n\ntool = FunctionTool.from_defaults(\n fn=my_function,\n name=\"my_tool\",\n description=\"Custom tool description\"\n)\n```\n\n资料来源：[llama-index-core/llama_index/core/tools/function_tool.py:100-200]()\n\n## Multi-Agent Workflows\n\nMulti-agent systems enable complex task decomposition where different specialized agents collaborate to solve problems.\n\n### Multi-Agent Workflow Architecture\n\n```mermaid\ngraph TD\n A[Coordinator Agent] --> B[Specialist Agent 1]\n A --> C[Specialist Agent 2]\n A --> D[Specialist Agent N]\n B --> E[Tool 1]\n C --> F[Tool 2]\n D --> G[Tool N]\n B --> A\n C --> A\n D --> A\n```\n\n### Workflow Communication\n\nAgents communicate through a shared state and message-passing mechanism:\n\n| Message Type | Direction | Purpose |\n|--------------|-----------|---------|\n| `task` | Coordinator → Specialist | Assign task |\n| `result` | Specialist → Coordinator | Return results |\n| `query` | Any → Any | Request information |\n| `response` | Any → Any | Provide information |\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:1-100]()\n\n### Creating Multi-Agent Systems\n\n```python\nfrom llama_index.core.agent.workflow import MultiAgentWorkflow\n\n# Create specialized agents\nresearch_agent = ReActAgent.from_tools(tools=[search_tool], name=\"researcher\")\nanalysis_agent = ReActAgent.from_tools(tools=[analysis_tool], name=\"analyst\")\n\n# Create multi-agent workflow\nworkflow = MultiAgentWorkflow(agents=[research_agent, analysis_agent])\n\n# Execute workflow\nresult = workflow.run(user_input=\"Analyze the latest research on AI\")\n```\n\n资料来源：[llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py:100-200]()\n\n## Tool Integration with LlamaIndex Readers\n\nThe Agent Framework integrates seamlessly with LlamaIndex's document readers, enabling agents to query and reason over loaded documents:\n\n```python\nfrom llama_index.core import VectorStoreIndex\nfrom llama_index.core.agent import ReActAgent\n\n# Load documents\ndocuments = SimpleDirectoryReader(\"./data\").load_data()\nindex = VectorStoreIndex.from_documents(documents)\n\n# Create query engine tool\nquery_tool = index.as_query_engine()\n\n# Create agent with query tool\nagent = ReActAgent.from_tools(tools=[query_tool])\nresponse = agent.chat(\"What is the main topic of these documents?\")\n```\n\nThis integration allows agents to:\n- Query vector databases\n- Retrieve relevant context\n- Synthesize information from multiple sources\n- Perform RAG (Retrieval-Augmented Generation)\n\n## Best Practices\n\n### Designing Effective Tools\n\n| Guideline | Rationale |\n|-----------|-----------|\n| Clear descriptions | Helps LLM understand when to use the tool |\n| Structured outputs | Easier for agent to parse and use results |\n| Error handling | Prevents agent crashes from tool failures |\n| Idempotent operations | Enables safe retries |\n\n### Agent Configuration\n\n| Parameter | Recommendation |\n|-----------|----------------|\n| `max_iterations` | Set based on task complexity (default: 10) |\n| `timeout` | Allow sufficient time for tool execution |\n| `memory_type` | Use conversation memory for multi-turn interactions |\n| `tool_retriever` | Implement for large tool collections |\n\n### Debugging Agents\n\n1. **Enable verbose mode** to see agent's reasoning traces\n2. **Log tool inputs/outputs** to verify correct tool usage\n3. **Test tools independently** before combining with agent\n4. **Monitor token usage** to prevent excessive spending\n\n## See Also\n\n- [ReAct Agent Documentation](https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/)\n- [Workflow Documentation](https://docs.llamaindex.ai/en/stable/module_guides/deploying/workflow/)\n- [Tool System](https://docs.llamaindex.ai/en/stable/module_guides/deploying/tools/)\n- [LlamaIndex Core](https://github.com/run-llama/llama_index/tree/main/llama-index-core)\n\n---\n\n\n\n## Memory Systems\n\n### 相关页面\n\n相关主题：[Agent Framework](#agent-framework), [Storage Systems](#storage-systems)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [llama-index-core/llama_index/core/memory/chat_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_memory_buffer.py)\n- [llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py)\n- [llama-index-core/llama_index/core/memory/vector_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/vector_memory.py)\n- [llama-index-core/llama_index/core/memory/simple_composable_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/simple_composable_memory.py)\n- [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n \n\n# Memory Systems\n\nMemory Systems in LlamaIndex provide persistent conversation history management for chat engines and agents. They enable AI applications to maintain context across multiple interactions, store user preferences, and retrieve relevant historical information during conversations.\n\n## Architecture Overview\n\nMemory Systems follow a modular architecture that allows different memory implementations to be composed and used interchangeably. The core memory system supports multiple storage strategies including buffer-based, summary-based, and vector-based retrieval.\n\n```mermaid\ngraph TD\n A[Chat Engine / Agent] --> B[Memory System]\n B --> C[ChatMemoryBuffer]\n B --> D[ChatSummaryMemoryBuffer]\n B --> E[VectorMemory]\n B --> F[Mem0Memory]\n C --> G[SimpleComposableMemory]\n D --> G\n E --> G\n F --> H[External Memory Services]\n \n G --> I[Storage Backend]\n H --> J[Mem0 Platform API]\n```\n\n## Core Memory Components\n\n### ChatMemoryBuffer\n\n`ChatMemoryBuffer` is the foundational memory component that stores conversation history in a simple buffer structure. It maintains a list of chat messages and provides methods for adding, retrieving, and managing conversation context.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `chat_history` | `List[ChatMessage]` | List of conversation messages |\n| `size` | `int` | Maximum number of messages to retain |\n| `tokenizer` | `Callable` | Function to count tokens |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/chat_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_memory_buffer.py)\n\n### ChatSummaryMemoryBuffer\n\n`ChatSummaryMemoryBuffer` extends the basic buffer with summarization capabilities. When the conversation exceeds the configured size, older messages are condensed into a summary rather than being discarded entirely.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `llm` | `LLM` | LLM instance for generating summaries |\n| `chat_history` | `List[ChatMessage]` | Initial conversation history |\n| `size` | `int` | Maximum buffer size before summarization |\n| `summary_exists` | `bool` | Flag indicating if summary is generated |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py)\n\n### VectorMemory\n\n`VectorMemory` uses vector embeddings to store and retrieve conversation history. This enables semantic search within the conversation history, allowing the system to find relevant past messages based on meaning rather than exact matches.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `vector_store` | `VectorStore` | Storage backend for embeddings |\n| `embed_model` | `EmbeddingModel` | Model for generating embeddings |\n| `index` | `VectorStoreIndex` | Index for efficient retrieval |\n| `retriever` | `BaseRetriever` | Retrieval mechanism |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/vector_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/vector_memory.py)\n\n### SimpleComposableMemory\n\n`SimpleComposableMemory` provides a framework for combining multiple memory types into a unified interface. This allows different memory strategies to work together, leveraging the strengths of each approach.\n\n| Feature | Description |\n|---------|-------------|\n| Memory Composition | Combine buffer, summary, and vector memories |\n| Unified Interface | Single API for all memory operations |\n| Flexible Retrieval | Query multiple memory sources simultaneously |\n\n**资料来源：** [llama-index-core/llama_index/core/memory/simple_composable_memory.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/simple_composable_memory.py)\n\n## Mem0 Memory Integration\n\nThe `Mem0Memory` integration provides access to the Mem0 Platform for advanced memory management. Mem0 offers enhanced capabilities for semantic memory storage, user preference tracking, and cross-session persistence.\n\n### Configuration Options\n\n#### Client-Based Initialization\n\n```python\nfrom llama_index.memory.mem0 import Mem0Memory\n\ncontext = {\"user_id\": \"user_1\"}\nmemory = Mem0Memory.from_client(\n context=context,\n api_key=\"\",\n search_msg_limit=4,\n)\n```\n\n#### Config Dictionary Initialization\n\n```python\nmemory = Mem0Memory.from_config(\n context=context,\n config={\n \"provider\": \"openai\",\n \"config\": {\"model\": \"text-embedding-3-small\"},\n \"version\": \"v1.1\",\n },\n search_msg_limit=4,\n)\n```\n\n### Context Parameters\n\nThe Mem0 context identifies the entity for which memory is stored:\n\n| Parameter | Description |\n|-----------|-------------|\n| `user_id` | Unique identifier for the user |\n| `agent_id` | Unique identifier for the agent |\n| `run_id` | Unique identifier for the conversation run |\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Usage Patterns\n\n### Integration with SimpleChatEngine\n\n```python\nfrom llama_index.core import SimpleChatEngine\nfrom llama_index.memory.mem0 import Mem0Memory\n\nmemory = Mem0Memory.from_client(\n context={\"user_id\": \"user_1\"},\n api_key=\"\",\n)\n\nchat_engine = SimpleChatEngine.from_defaults(\n llm=llm,\n memory=memory\n)\n\nresponse = chat_engine.chat(\"Hi, My name is Mayank\")\n```\n\n### Integration with FunctionAgent\n\n```python\nfrom llama_index.core.tools import FunctionTool\nfrom llama_index.memory.mem0 import Mem0Memory\n\nmemory = Mem0Memory.from_client(\n context={\"user_id\": \"user_1\"},\n api_key=\"\",\n)\n\n# Use memory with agent for persistent context\nagent = FunctionAgent(\n llm=llm,\n tools=[call_tool, email_tool],\n memory=memory\n)\n```\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Memory Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant ChatEngine\n participant Memory\n participant Storage\n \n User->>ChatEngine: Send message\n ChatEngine->>Memory: Get context (search_msg_limit messages)\n Memory->>Storage: Query recent messages\n Storage-->>Memory: Return relevant messages\n Memory-->>ChatEngine: Context messages\n ChatEngine->>ChatEngine: Generate response\n ChatEngine->>Memory: Store new message\n Memory->>Storage: Persist message\n ChatEngine-->>User: Return response\n```\n\n## Comparison of Memory Types\n\n| Memory Type | Storage Method | Use Case | Scalability |\n|-------------|----------------|----------|-------------|\n| ChatMemoryBuffer | List/Buffer | Short conversations | Limited by token size |\n| ChatSummaryMemoryBuffer | Condensed summaries | Long conversations | Better for extended chats |\n| VectorMemory | Embeddings | Semantic search | Scales with vector store |\n| Mem0Memory | External API | Production applications | Cloud-native scaling |\n\n## Environment Configuration\n\nFor Mem0 integration, set the API key as an environment variable:\n\n```bash\nexport MEM0_API_KEY=\"\"\n```\n\nFor LLM integration within memory operations:\n\n```bash\nexport OPENAI_API_KEY=\"\"\n```\n\n**资料来源：** [llama-index-integrations/memory/llama-index-memory-mem0/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/memory/llama-index-memory-mem0/README.md)\n\n## Best Practices\n\n1. **Choose Appropriate Memory Type**: Select based on conversation length and retrieval needs\n2. **Configure Token Limits**: Set appropriate `search_msg_limit` to balance context and performance\n3. **Use Context Parameters**: Always provide user_id, agent_id, or run_id for proper memory isolation\n4. **Consider Composability**: Use `SimpleComposableMemory` for complex memory requirements\n5. **Monitor API Costs**: When using Mem0, track API usage for cost optimization\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：run-llama/llama_index\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo: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摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo: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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for run-llama/llama_index.\n\nProject:\n- Name: llama_index\n- Repository: https://github.com/run-llama/llama_index\n- Summary: LlamaIndex is the leading document agent and OCR platform\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: LlamaIndex is the leading document agent and OCR platform\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: LlamaIndex is the leading document agent and OCR platform\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to LlamaIndex. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. core-architecture: Core Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. documents-nodes: Documents and Nodes. Produce one small intermediate artifact and wait for confirmation.\n5. storage-systems: Storage Systems. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- docs/src/content/docs/framework/getting_started/concepts.mdx\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/base/llms/base.py\n- llama-index-core/llama_index/core/base/embeddings/base.py\n- llama-index-core/llama_index/core/base/response/schema.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}