LlamaIndex
核对日期：2026-05-09。
10.10 上线验收补充
| 验收项 | 通过标准 |
|---|---|
| 入库治理 | source_id、owner、ACL、时间戳和版本齐全 |
| 检索评测 | recall@k、引用准确率和拒答正确率达标 |
| 权限 | 检索前过滤，跨租户文档不可召回 |
| 注入防护 | 恶意文档只作为数据，不驱动工具调用 |
| 数据删除 | 删除请求能从索引、缓存和引用中清理 |
| 证据回放 | 每个答案能回到检索片段和索引版本 |
1. 定义与边界
LlamaIndex 是以数据连接、索引、检索增强生成（RAG）和知识型 Agent 为核心的 LLM 应用框架。它适合把企业数据、文档、数据库和工具接入 Agent，不应被理解为只做向量数据库封装。
2. 官方能力、社区能力、实验能力和营销说法
| 类型 | 内容 |
|---|---|
| 官方能力 | readers/connectors、index、retriever、query engine、agent、workflow、observability 集成 |
| 社区能力 | 第三方数据源 reader、向量库、工具和模板 |
| 实验/快速变化 | 工作流、Agent API、部分云服务和集成 |
| 营销说法 | “接入企业知识库即可避免幻觉”不成立，仍需检索评测和引用校验 |
3. 核心机制
LlamaIndex 的优势是围绕数据管道和 RAG 组织 Agent，而不是只让模型自由调用工具。
4. 架构与工程实现
适合场景：
| 场景 | 设计 |
|---|---|
| 企业文档问答 | ingestion + index + retriever + citation |
| 数据分析 Agent | database/tool + query planning |
| 多知识源整合 | router retriever 或 query engine |
| 数据驱动 workflow | LlamaIndex workflow 管理步骤 |
数据节点建议保留元数据：
{
"doc_id": "hr-policy-2026",
"chunk_id": "hr-policy-2026#12",
"source": "confluence",
"acl": ["hr", "manager"],
"updated_at": "2026-05-01",
"text": "..."
}
5. 生产实践
- ingestion、chunking、embedding、reranking 和生成要分开评测。
- 检索必须尊重 ACL，不能让向量相似度绕过权限。
- 对索引增量更新和删除做一致性检查。
- 输出需要引用来源，并在证据不足时拒答或请求补充。
- 对 reader 和 connector 做供应链审查。
6. 常见反模式
| 反模式 | 后果 |
|---|---|
| 默认 chunking 上生产 | 关键上下文被切断 |
| 只看答案流畅度 | 检索失败被模型掩盖 |
| 忽略文档时间戳 | 使用过期政策 |
| 无 ACL 过滤 | 跨租户或跨部门泄漏 |
7. 评测方法
RAG/Agent 评测应拆为检索召回率、重排质量、引用准确率、答案 groundedness、拒答正确率和端到端成功率。建议维护包含冲突文档、过期文档和权限边界的数据集。
8. 安全与治理
主要风险是敏感文档进入错误上下文、外部文档注入、引用伪造和数据源凭证泄露。治理措施包括 ACL 前置过滤、source metadata、工具最小权限和审计。
9. 权威资料
- LlamaIndex docs: https://docs.llamaindex.ai/en/stable/
- LlamaIndex agents: https://docs.llamaindex.ai/en/stable/understanding/agent/
- LlamaIndex workflows: https://docs.llamaindex.ai/en/stable/module_guides/workflow/
- LlamaIndex evaluation: https://docs.llamaindex.ai/en/stable/module_guides/evaluating/
- LlamaIndex GitHub: https://github.com/run-llama/llama_index
10. 二次精修：数据型 Agent 决策材料
10.1 当前官方能力
| 能力 | 作用 | 决策含义 |
|---|---|---|
| Data connectors / readers | 接入文件、数据库、SaaS、网页 | 适合数据源多的 RAG |
| Index / retriever / query engine | 建索引、检索、问答 | 适合知识库和搜索增强 |
| Agents | 用工具和数据源完成任务 | 适合数据密集型 Agent |
| Workflows | 事件驱动、可组合流程 | 适合把 RAG 与工具流程编排 |
| Evaluation / observability | 评测检索和生成质量 | 适合建立 RAG 回归集 |
10.2 适用场景
| 场景 | 推荐原因 |
|---|---|
| 企业文档问答 | 数据接入、索引和检索能力完整 |
| 研究/分析 Agent | 多数据源、多步骤查询、引用追踪 |
| 需要对 RAG 质量细粒度调优 | 检索、重排、评测组件清晰 |
| 要把数据管道和 Agent 合并 | workflows 可组织数据处理链路 |
10.3 不适用场景
- 主要是业务写操作、审批和状态机，不是数据检索，优先工作流/图框架。
- 数据权限非常复杂但无法在检索前过滤，任何 RAG 框架都不应直接接入。
- 极简工具调用或纯聊天应用，LlamaIndex 可能过重。
10.4 数据流架构
10.5 生产实践
- 文档入库时保留
source_id、owner、tenant、acl、effective_at、expires_at。 - 检索前做权限过滤，不要检索后再让模型“不要看无权限内容”。
- 对切分、embedding、rerank、top_k、引用规则建立版本。
- 对过期文档、冲突文档和低可信来源建立降权或拒答策略。
- 数据源凭证由连接器代理，不进入 prompt 和日志。
10.6 评测矩阵
| 评测项 | 指标 |
|---|---|
| 检索 | recall@k、MRR、权限过滤正确率 |
| 生成 | groundedness、引用准确率、拒答正确率 |
| 数据治理 | 过期文档命中率、跨租户泄露率 |
| Agent | 工具选择准确率、多跳任务成功率 |
| 安全 | 注入文档成功率、敏感字段外发率 |
10.7 反模式补充
| 反模式 | 后果 |
|---|---|
| 只调 top_k 直到答案看起来好 | 成本上升且可能引入噪声 |
| 不保存检索证据 | 无法解释错误答案 |
| 文档入库无 owner 和 ACL | 无法满足企业权限和删除请求 |
| 用 RAG 替代数据权限系统 | 跨租户泄露风险 |
10.8 集成边界
| 边界 | 建议 |
|---|---|
| 与 LangGraph | LlamaIndex 负责数据检索，LangGraph 负责长流程状态 |
| 与业务数据库 | 读操作通过受控查询层，写操作走业务 API |
| 与低代码平台 | 平台可做入口，索引和评测仍需工程化管理 |
| 与安全系统 | 接入 DLP、ACL、审计和数据保留策略 |
10.9 迁移策略
- 从传统搜索迁移：先并行评测检索召回，再接入生成回答。
- 从简单 RAG 迁移：先补 metadata 和 eval，再替换索引/检索组件。
- 从 LangChain 迁移：保留业务工具，逐步把数据接入和 query engine 迁到 LlamaIndex。
核对日期：2026-05-09。