1. 项目概述：不是让大模型“背数据”，而是让它“懂数据”

你有没有试过把一份30页的PDF产品说明书喂给ChatGPT，然后问：“第17页提到的故障代码E42对应哪几种可能原因？”——结果它要么胡编一个，要么直接说“我无法访问文件内容”。这不是模型能力不行，而是你没给它配一把能打开你数据仓库的钥匙。LlamaIndex干的就是这件事：它不改变LLM本身，也不要求你微调模型参数，而是像一位经验丰富的图书管理员+翻译官+索引工程师三合一的角色，在你的私有数据和大语言模型之间搭起一座结构清晰、响应精准、可追溯来源的桥梁。核心关键词就三个： LlamaIndex、私有数据、LLM增强检索 。它解决的不是“能不能聊”，而是“聊得准不准、答得有没有依据、改起来方不方便”这三个真实业务场景中的卡点。适合谁？不是只写demo的极客，而是每天被销售合同、客服工单、内部Wiki、产品日志压得喘不过气的中台工程师、知识管理负责人、AI应用落地PM——你们手里的数据不是“待处理的垃圾”，而是沉睡的金矿；LlamaIndex就是那台低门槛、高精度、可审计的淘金机。它不承诺“一键AGI”，但能让你在三天内上线一个真正能回答“上季度华东区退货率异常升高，具体是哪三类SKU导致的？”这种问题的知识助手。我去年帮一家医疗器械公司落地时，他们原有客服系统平均响应时长是8分23秒，接入LlamaIndex重构知识检索层后，首问解决率从61%提升到89%，而且每条回答都带原文段落定位，法务审核时直接点开就能核对，这才是企业级AI该有的样子。

2. 整体设计思路：为什么不是RAG，而是“RAG+”的工程化升级

很多人第一反应是：“这不就是RAG（检索增强生成）吗？”——没错，但LlamaIndex远不止于此。它把RAG从一个概念性方案，变成了可拆解、可调试、可监控、可迭代的工业级数据管道。传统RAG常犯三个致命错误：一是把所有文档粗暴切块扔进向量库，导致关键上下文被割裂；二是检索时只靠相似度打分，完全忽略文档结构、语义权重、时效性等业务逻辑；三是生成阶段把检索结果当“原料”直接塞给LLM，不加清洗、不控长度、不标来源，结果幻觉得比原始数据还严重。LlamaIndex的设计哲学恰恰反其道而行之： 数据预处理是核心，不是前置步骤；检索是可控的查询引擎，不是黑盒匹配；生成是受约束的推理过程，不是自由发挥 。它用一套统一抽象（Document → Node → Index）把异构数据源（PDF/Excel/API/数据库）标准化为可计算的“知识单元”，再通过多级索引策略（向量索引、关键词索引、混合索引、图索引）实现“查得准”，最后用Query Engine封装检索-重排-提示工程-生成-溯源的全链路，确保输出既准确又可验证。举个实际例子：我们处理某车企的维修手册时，发现单纯用向量检索会把“刹车片更换”和“ABS系统校准”混在一起（因为都含“制动”），但LlamaIndex支持在Node层面打标签（如 section_type: procedure , criticality: high , last_updated: 2024-03-15 ），查询时可强制要求 section_type == "procedure" 且 criticality == "high" ，这就把业务规则直接编译进了检索逻辑里。这种能力不是靠调参，而是靠它的数据建模范式决定的。所以它不是RAG的替代品，而是把RAG从实验室Demo推向产线部署的关键拼图——就像当年Linux把Unix从学术圈带进服务器机房一样，LlamaIndex正在把RAG从技术博客带进财务报表。

2.1 数据建模：Document、Node、Index三层抽象的实战意义

LlamaIndex最反直觉也最有价值的设计，是强制你把数据“掰开揉碎再重组”。它不接受“一份PDF就是一个Document”的懒人思维，而是要求你定义：这份PDF里哪些是元数据（作者、版本号、生效日期）、哪些是章节标题（需要保留层级关系）、哪些是表格（需转为结构化数据）、哪些是脚注（需单独提取并关联）。这个过程叫 Node化 ——每个Node是一个最小语义单元，可以是一段文字、一个表格、一张图片的OCR文本，甚至是一段SQL查询结果。我见过太多团队跳过这步直接建向量库，结果上线后发现：用户问“2023年Q4营收是多少”，系统返回了年报PDF第一页的摘要段落，但真正的数字藏在附录表12的第三列——因为切块时把表格整个切掉了。LlamaIndex的Node化解决了这个问题：它提供 MarkdownNodeParser 自动识别标题层级， PandasNodeParser 把Excel每张Sheet转为独立Node， UnstructuredReader 调用Unstructured.io精准提取PDF中的表格和图表文字。更关键的是，Node自带 metadata 字段，你可以手动注入业务属性。比如处理合同库时，我给每个Node加了 contract_type: NDA , party_a: TechCorp , expiry_date: 2025-12-31 ，后续查询“找出所有2025年底前到期的NDA合同”时，根本不用走向量检索，直接用 MetadataIndex 做精确匹配，速度比向量搜索快10倍以上。Index层则是Node的组织方式： VectorStoreIndex 适合语义模糊查询（如“跟数据安全相关的条款”）， SimpleKeywordTableIndex 适合关键词精确匹配（如“GDPR第32条”）， SummaryIndex 则把整份文档压缩成一段摘要Node，用于快速概览。三者可组合使用——这才是它超越简单RAG的地方：不是非此即彼的选择题，而是按需装配的乐高积木。

2.2 查询引擎：从“搜关键词”到“执行业务逻辑”的跃迁

如果你以为LlamaIndex的Query Engine只是把检索结果拼进prompt，那就低估了它的工程深度。它把一次查询拆解为五个可干预环节： 1）查询解析（Query Parsing）→ 2）检索（Retrieval）→ 3）重排（Reranking）→ 4）提示组装（Prompt Assembly）→ 5）生成与后处理（Generation & Post-processing） 。每个环节都开放API，允许你插入自定义逻辑。比如在金融合规场景，用户问“客户A的KYC更新是否符合最新监管要求？”，标准流程会检索所有KYC文档，但LlamaIndex允许你在检索后插入一个 CustomReranker ：先检查每个Node的 regulation_version 元数据，过滤掉早于2024年1月1日的条款；再调用规则引擎判断“客户A所属国家”是否触发特定监管分支；最后才把剩余Node送入LLM。这已经不是RAG，而是 规则驱动的RAG+ 。另一个典型场景是多跳问答（Multi-hop QA）：“对比产品X和Y在电池续航和防水等级上的差异”。传统方案会分别检索X和Y的文档，再让LLM对比——但若X文档提续航不提防水，Y文档提防水不提续航，LLM就容易编造。LlamaIndex的 SubQuestionQueryEngine 会自动拆解为两个子问题：“产品X的电池续航是多少？”、“产品X的防水等级是多少？”，并行检索，再聚合结果。我们实测某手机厂商的规格库时，多跳问题准确率从52%提升到91%。更隐蔽的价值在于 可审计性 ：Query Engine默认记录每次查询的完整trace，包括检索到的Node ID、重排分数、最终输入LLM的prompt文本、生成结果的token消耗。当法务质疑“为什么说这款设备支持IP68？”时，你不需要翻日志，直接调用 query_engine.get_response_trace() 就能返回带时间戳的溯源证据链——这对企业级AI落地不是锦上添花，而是生死线。

3. 核心细节解析：从零搭建一个可落地的知识助手

现在我们动手搭一个真实可用的系统。目标很明确：让销售团队能用自然语言查询《2024版渠道政策白皮书》（PDF格式），例如“华北区代理商返点比例是多少？”、“二级代理首次进货满多少万可获赠培训名额？”。整个过程分四步：环境准备→数据加载与索引构建→查询引擎配置→生产化部署。每一步都有坑，我会把踩过的雷和绕过去的捷径全告诉你。

3.1 环境准备：选对Python版本和依赖组合，省下三天调试时间

别急着 pip install llama-index 。LlamaIndex对Python版本和底层依赖极其敏感，我见过太多团队卡在第一步。 必须用Python 3.10或3.11 ——3.12太新，部分依赖（如llama-cpp-python）还没适配；3.9太老，asyncio行为不一致。虚拟环境用 venv 就行，别用conda，后者容易引发numpy版本冲突。核心依赖清单如下（直接复制粘贴）：

pip install "llama-index==0.10.30" \
  "llama-index-embeddings-huggingface==0.1.10" \
  "llama-index-vector-stores-chroma==0.1.5" \
  "unstructured[all]==0.10.30" \
  "pypdf==3.17.2" \
  "markdown-it-py==3.0.0"

重点解释三个易错点：

1. LlamaIndex主版本锁定为0.10.30 ：这是目前最稳定的LTS版本。0.11.x系列引入了AsyncNodeParser等新特性，但文档不全，且与旧版API不兼容；0.9.x又缺少关键修复（如PDF表格识别bug）。我们线上服务已稳定运行7个月，零因版本升级导致故障。
2. Embedding模型必须用HuggingFace版 ：官方推荐的OpenAIEmbedding在企业内网不可用，而 llama-index-embeddings-huggingface 支持本地部署的bge-small-zh-v1.5（中文效果最佳）。安装时注意： transformers>=4.35.0 ，否则会报 AutoTokenizer 找不到。
3. Unstructured必须装all extras ： unstructured[all] 包含PDF解析所需的poppler（Linux/Mac）和pdf2image（Windows）依赖。如果只装 unstructured 基础包，PDF里的表格和图片文字将全部丢失——这是90%新手遇到的第一个崩溃点。

提示：Windows用户务必提前安装Visual Studio Build Tools（而非仅Python），否则 unstructured 编译会失败。Mac用户若用M1芯片，需在终端执行 export ARCHFLAGS="-arch arm64" 再安装，否则llama-cpp-python会报架构错误。

3.2 数据加载与索引构建：如何让PDF里的表格“活过来”

假设你的白皮书叫 channel_policy_2024.pdf ，放在 ./data/ 目录下。别用 SimpleDirectoryReader ——它连页眉页脚都分不清。正确做法是分层解析：

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Settings
from llama_index.core.node_parser import MarkdownNodeParser
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from unstructured.partition.pdf import partition_pdf

# 步骤1：用Unstructured精准解析PDF（保留表格结构）
elements = partition_pdf(
    filename="./data/channel_policy_2024.pdf",
    strategy="hi_res",  # 高精度模式，识别表格和图片
    infer_table_structure=True,  # 关键！开启表格结构推断
    include_page_numbers=True,  # 后续溯源必需
)

# 步骤2：将Unstructured elements转为LlamaIndex Document
from llama_index.core import Document
documents = []
for element in elements:
    if hasattr(element, 'text') and element.text.strip():
        # 为表格元素添加特殊标记，便于后续提示工程识别
        extra_info = {"source": "table"} if element.category == "Table" else {}
        doc = Document(
            text=element.text,
            metadata={
                "page_number": element.metadata.page_number,
                "category": element.category,
                **extra_info
            }
        )
        documents.append(doc)

# 步骤3：Node化——用MarkdownNodeParser保留标题层级
parser = MarkdownNodeParser()
nodes = parser.get_nodes_from_documents(documents)

# 步骤4：构建混合索引（向量+关键词）
from llama_index.core import StorageContext, load_index_from_storage
from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb

# 初始化ChromaDB（轻量级，适合中小规模）
db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("channel_policy")

vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 设置Embedding模型（本地部署bge-small-zh-v1.5）
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-zh-v1.5",
    device="cpu",  # GPU非必需，CPU足够快
    cache_folder="./models"
)

# 构建索引（耗时约2分钟，PDF共42页）
index = VectorStoreIndex(
    nodes,
    storage_context=storage_context,
    show_progress=True
)

这段代码的关键细节：

• infer_table_structure=True 让Unstructured把PDF表格转为Markdown表格语法（ | 列1 | 列2 | ），NodeParser能原样保留，后续LLM看到 | 返点比例 | 华北区 | 华东区 | 就知道这是结构化数据，不会当成普通段落胡说。
• metadata 里存 page_number 和 category ，查询时可强制要求 "page_number > 10" 或 "category == 'Table' ，精准定位。
• device="cpu" 是故意的：bge-small-zh-v1.5在CPU上单次embedding耗时<150ms，比调用API更稳，且无网络延迟。我们实测1000个Node的embedding总耗时2分17秒，完全可接受。

注意：如果PDF有扫描件（图片型PDF），必须先用OCR。Unstructured的 strategy="hi_res" 会自动调用Tesseract，但需提前安装 tesseract-ocr （Ubuntu: sudo apt install tesseract-ocr ，Mac: brew install tesseract ）。否则所有扫描页内容为空。

3.3 查询引擎配置：让回答带来源、控长度、防幻觉

索引建好只是开始，Query Engine才是灵魂。默认的 index.as_query_engine() 太粗糙，必须定制：

from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector
from llama_index.core import get_response_synthesizer
from llama_index.core.response_synthesizers import TreeSummarize
from llama_index.core.prompts import PromptTemplate

# 步骤1：定义专用提示词（防幻觉核心！）
QA_PROMPT_TMPL_STR = (
    "上下文信息如下：\n"
    "---------------------\n"
    "{context_str}\n"
    "---------------------\n"
    "请根据上述上下文信息，回答以下问题。\n"
    "要求：\n"
    "1. 只回答问题，不添加任何推测、解释或额外信息；\n"
    "2. 若上下文中没有明确答案，必须回答'未在政策文件中找到相关信息'；\n"
    "3. 所有数值、百分比、金额必须严格引用原文，不得四舍五入；\n"
    "4. 回答末尾必须标注来源：'（来源：第{page_number}页，{category}）'\n"
    "问题：{query_str}\n"
    "答案："
)
qa_prompt_tmpl = PromptTemplate(QA_PROMPT_TMPL_STR)

# 步骤2：配置响应合成器（控制长度和结构）
response_synthesizer = get_response_synthesizer(
    text_qa_template=qa_prompt_tmpl,
    response_mode="compact",  # 只返回最相关片段，避免冗余
    streaming=False
)

# 步骤3：构建查询引擎（启用重排和溯源）
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.core.query_engine import RetrieverQueryEngine

retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=5,  # 检索5个最相关Node
    vector_store_query_mode="default"
)

# 添加重排器：按页码和类别加权（表格比正文权重高20%）
from llama_index.core.retrievers import BaseRetriever
class PageWeightedRetriever(BaseRetriever):
    def _retrieve(self, query_bundle):
        nodes = retriever._retrieve(query_bundle)
        for node in nodes:
            # 表格Node权重+0.2，页码>20的Node权重+0.1（政策细则页）
            weight = 1.0
            if node.metadata.get("category") == "Table":
                weight += 0.2
            if node.metadata.get("page_number", 0) > 20:
                weight += 0.1
            node.score *= weight
        return sorted(nodes, key=lambda x: x.score, reverse=True)[:3]

weighted_retriever = PageWeightedRetriever()

query_engine = RetrieverQueryEngine(
    retriever=weighted_retriever,
    response_synthesizer=response_synthesizer
)

# 测试查询
response = query_engine.query("华北区代理商返点比例是多少？")
print(str(response))
# 输出示例："华北区代理商返点比例为12.5%。（来源：第18页，Table）"

这个配置的实战价值：

• 防幻觉机制 ：提示词第2条强制LLM承认“不知道”，杜绝编造。我们上线前用100个测试问题验证，幻觉率从37%降至0%。
• 溯源强制 ： （来源：第18页，Table） 不是装饰，是法务审核的凭证。销售拿这个去跟客户谈返点，客户可当场翻PDF第18页核对。
• 重排逻辑 ：表格Node权重更高，因为政策细则多以表格呈现；页码>20的Node权重更高，因为附录页往往含关键条款。这比纯向量相似度更贴近业务逻辑。

实操心得：不要迷信“top_k越大越好”。我们测试过top_k=10，结果LLM被无关信息干扰，准确率反而下降。top_k=3配合重排，是精度和效率的最佳平衡点。

4. 实操过程：从本地Demo到生产环境的七步通关

本地跑通只是起点，真正在企业环境落地要过七道关。我把每一步的命令、配置、验证方法、常见报错都列出来，照着做就能上线。

4.1 第一步：本地验证（5分钟）

在Python脚本末尾加：

# 快速验证：检查索引是否正常
print(f"索引节点数：{len(index.docstore.docs)}")
print(f"前3个Node的元数据：{list(index.docstore.docs.values())[:3]}")

# 测试基础查询
test_queries = [
    "二级代理首次进货满多少万可获赠培训名额？",
    "渠道政策何时生效？",
    "哪些情况会导致返点取消？"
]
for q in test_queries:
    try:
        res = query_engine.query(q)
        print(f"Q: {q}\nA: {str(res)}\n---")
    except Exception as e:
        print(f"Q: {q} -> 错误: {e}")

预期输出 ：

• 节点数应与PDF页数×3大致相当（每页切出3-5个Node）；
• 元数据显示 page_number 和 category 字段存在；
• 三个问题均返回带来源标注的答案，无 KeyError 或 None 。

典型报错及解法 ：

• AttributeError: 'NoneType' object has no attribute 'text' ：PDF解析失败，检查 partition_pdf 是否返回空列表，确认PDF不是加密或损坏；
• ValueError: No nodes found ：NodeParser未生效，检查是否漏了 parser.get_nodes_from_documents(documents) 这行。

4.2 第二步：性能压测（15分钟）

用 locust 模拟并发查询，验证响应时间：

pip install locust

创建 locustfile.py ：

from locust import HttpUser, task, between
import json

class LlamaIndexUser(HttpUser):
    wait_time = between(1, 3)
    
    @task
    def query_policy(self):
        # 模拟真实查询
        queries = [
            "华北区返点比例",
            "培训名额获取条件",
            "违约金计算方式"
        ]
        import random
        q = random.choice(queries)
        
        # 注意：这里调用的是你封装的API端点，非LlamaIndex原生接口
        self.client.post("/api/query", json={"query": q})

启动压测： locust -f locustfile.py --host http://localhost:8000 ，设置10用户、每秒1个请求。 合格线 ：95%请求响应时间<1.2秒，错误率0%。若超时，检查ChromaDB是否启用了 persist_directory （否则每次重启清空索引）。

4.3 第三步：API封装（20分钟）

用FastAPI暴露查询接口，关键是要加缓存和限流：

from fastapi import FastAPI, HTTPException, Depends
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded

app = FastAPI()
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

# 缓存查询结果（内存级，简单有效）
from functools import lru_cache
@lru_cache(maxsize=1000)
def cached_query(query: str) -> str:
    return str(query_engine.query(query))

@app.post("/api/query")
@limiter.limit("10/minute")  # 防暴力查询
async def query_policy(query: dict):
    try:
        result = cached_query(query["query"])
        return {"answer": result, "status": "success"}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

启动： uvicorn main:app --reload --port 8000 。用curl测试：

curl -X POST "http://localhost:8000/api/query" \
  -H "Content-Type: application/json" \
  -d '{"query":"华北区返点比例"}'

必须验证 ：连续请求10次，第11次返回429状态码（限流生效）；首次查询耗时>1s，第二次<100ms（缓存生效）。

4.4 第四步：前端集成（30分钟）

用Vue3快速搭管理界面，核心是展示溯源信息：

<template>
  <div class="chat-container">
    <div v-for="msg in messages" :key="msg.id" class="message">
      <div class="answer">{{ msg.answer }}</div>
      <div class="source" v-if="msg.source">
        <span>来源：</span>
        <span @click="jumpToPage(msg.source.page)">第{{ msg.source.page }}页</span>
        <span v-if="msg.source.category">（{{ msg.source.category }}）</span>
      </div>
    </div>
  </div>
</template>

<script setup>
// 解析来源字符串：'（来源：第18页，Table）' -> {page: 18, category: 'Table'}
const parseSource = (str) => {
  const match = str.match(/第(\d+)页，(\w+)/);
  return match ? { page: parseInt(match[1]), category: match[2] } : null;
};
</script>

关键体验 ：点击“第18页”应跳转到PDF查看器的对应页码。我们用 pdfjs-dist 实现，10行代码搞定页面跳转。

4.5 第五步：增量更新（10分钟）

政策会修订，索引不能重做。LlamaIndex支持增量更新：

# 加载新PDF（如channel_policy_2024_v2.pdf）
new_docs = SimpleDirectoryReader("./data/").load_data()
new_nodes = parser.get_nodes_from_documents(new_docs)

# 删除旧索引中同名文档（按metadata标识）
index.delete_ref_doc("channel_policy_2024.pdf", delete_from_docstore=True)

# 插入新Node
index.insert_nodes(new_nodes)
index.storage_context.persist("./chroma_db")  # 持久化

验证方法 ：更新后查“2024年Q2新增条款”，答案应来自新PDF，且 page_number 是新版页码。

4.6 第六步：监控告警（15分钟）

用Prometheus暴露指标：

from prometheus_client import Counter, Histogram, Gauge
import time

QUERY_COUNT = Counter('llamaindex_query_total', 'Total queries')
QUERY_LATENCY = Histogram('llamaindex_query_latency_seconds', 'Query latency')
ACTIVE_USERS = Gauge('llamaindex_active_users', 'Active users')

@app.middleware("http")
async def add_metrics(request, call_next):
    start_time = time.time()
    QUERY_COUNT.inc()
    ACTIVE_USERS.inc()
    response = await call_next(request)
    ACTIVE_USERS.dec()
    QUERY_LATENCY.observe(time.time() - start_time)
    return response

配置Grafana看板，监控三项核心指标：查询P95延迟、错误率、活跃用户数。阈值设为：延迟>2s告警，错误率>1%告警。

4.7 第七步：安全加固（20分钟）

企业环境必须做三件事：

1. API密钥认证 ：在FastAPI中加 APIKeyHeader 依赖，所有请求必须带 X-API-Key ；
2. PDF上传限制 ：前端禁用 .exe 等危险扩展名，后端用 python-magic 校验文件MIME类型，只允许 application/pdf ；
3. 输出脱敏 ：在 response_synthesizer 后加中间件，用正则过滤手机号、身份证号等PII信息。

import re
def sanitize_output(text: str) -> str:
    # 脱敏手机号
    text = re.sub(r'1[3-9]\d{9}', '1XXXXXXXXXX', text)
    # 脱敏身份证号（18位）
    text = re.sub(r'\d{17}[\dXx]', 'XXXXXXXXXXXXXXXXXX', text)
    return text

# 在API返回前调用
return {"answer": sanitize_output(str(result)), "status": "success"}

最终验收清单 ：

• [ ] 任意PDF上传后，5分钟内可查询；
• [ ] 并发10用户时，P95延迟<1.5s；
• [ ] 查询结果100%带来源标注；
• [ ] 连续查询100次，无内存泄漏（ ps aux | grep uvicorn 进程RSS稳定）；
• [ ] 上传非PDF文件，返回400错误且无堆栈泄露。

5. 常见问题与排查技巧实录：那些文档里不会写的真相

LlamaIndex文档写得像学术论文，但真实落地全是血泪教训。我把高频问题按发生阶段归类，给出可立即执行的解决方案。

5.1 数据加载阶段：90%的失败源于PDF解析

问题现象	根本原因	一招解决
partition_pdf 返回空列表	PDF是扫描件且未装Tesseract，或PDF加密	运行 pdfinfo your.pdf 检查 Encrypted: yes ；若加密，用Adobe Acrobat解密；若扫描， sudo apt install tesseract-ocr 后重试
表格内容变成乱码（如 ）	PDF字体嵌入不全，Unstructured无法映射字符	在 partition_pdf 中加参数 encoding="utf-8" ，或改用 strategy="ocr_only" 强制OCR
页码错乱（第10页显示page_number=1）	PDF有封面/目录页，Unstructured从第一页计数	用 pdfseparate 拆分PDF，只传正文部分给 partition_pdf

实操心得：永远先用 unstructured 的CLI工具验证解析效果： unstructured-ingest pdf --input-path ./data/ --output-dir ./debug/ ，然后打开 ./debug/ 里的JSON，肉眼检查 text 和 category 字段是否合理。这比调试Python代码快10倍。

5.2 索引构建阶段：向量搜索不准的三大元凶

向量搜索不准不是模型问题，而是数据或配置问题。我们总结出三个必查点：

1. Embedding模型与查询语言不匹配 ：用英文模型 all-MiniLM-L6-v2 处理中文PDF，相似度分数全在0.2以下。解决方案：中文必须用 BAAI/bge-small-zh-v1.5 ，且 Settings.embed_model 要在 index 创建 前 设置，否则无效。

2. Node切分粒度失衡 ：把整页PDF当一个Node，导致“返点比例”和“违约责任”混在一个Node里，检索时无法分离。解决方案：用 SentenceSplitter 替代默认切分器， chunk_size=256, chunk_overlap=20 ，确保每个Node聚焦一个主题。

3. 元数据污染向量空间 ：把 filename 、 author 等字符串塞进Node的 text 字段，这些噪声词会稀释语义向量。解决方案：元数据只放 metadata 字典， text 字段纯净。

独家技巧：用 index.ref_doc_info 检查每个Document的Node分布。若某PDF生成了100个Node，但90个Node的 score 都<0.1，说明切分失败，需调整 SentenceSplitter 参数。

5.3 查询阶段：为什么答案总是“未找到”？

这是最打击信心的问题。排查路径必须按顺序：

1. 查检索结果 ：在 query_engine 中临时加日志：

   from llama_index.core.retrievers import VectorIndexRetriever
   original_retrieve = VectorIndexRetriever._retrieve
   def debug_retrieve(self, query_bundle):
       nodes = original_retrieve(self, query_bundle)
       print(f"检索到{len(nodes)}个Node，相似度：{[n.score for n in nodes]}")
       return nodes
   VectorIndexRetriever._retrieve = debug_retrieve
   

   若 len(nodes)==0 ，问题在检索层；若 len(nodes)>0 但答案错，问题在提示工程。

2. 查提示词注入 ：打印最终发送给LLM的prompt：

   from llama_index.core import get_response_synthesizer
   original_synthesize = get_response_synthesizer().synthesize
   def debug_synthesize(self, query, nodes):
       print("Prompt sent to LLM:")
       print(self.text_qa_template.format(context_str="\n".join([n.text for n in nodes]), query_str=query))
       return original_synthesize(self, query, nodes)
   

3. 查LLM响应 ：若prompt正确但LLM胡说，换更小的模型（如 gpt-3.5-turbo-1106 比 gpt-4-turbo 更少幻觉），或加强提示词约束（如增加“禁止使用‘可能’、‘大概’等模糊词汇”）。

5.4 生产环境：OOM、慢查询、冷启动的终极解法

• OOM（内存溢出） ：ChromaDB默认把整个向量库加载到内存。解决方案： chroma_collection = db.get_or_create_collection("name", embedding_function=None) 关闭自动embedding，或改用 QdrantVectorStore （支持磁盘存储）。

• 慢查询（>3s） ：90%是ChromaDB未建索引。解决方案： chroma_collection.create_index(index_name="idx", metric="cosine") ，或升级到Chroma 0.4.23+，默认启用HNSW索引。

• 冷启动慢（首次查询>5s） ：Embedding模型首次加载耗时。解决方案：在FastAPI启动时预热：

  @app.on_event("startup")
  async def startup_event():
      # 预热Embedding模型
      _ = Settings.embed_model.get_text_embedding("预热文本")
  

最后分享一个血泪教训：某次上线后用户反馈“查不到返点”，我们查日志发现所有查询都返回 未在政策文件中找到相关信息 。排查3小时才发现——PDF文件名是 channel_policy_2024_v2.pdf ，但销售同事发给客户的邮件里写的是 2024版渠道政策.pdf ，用户复制粘贴时带了中文括号 （） ，而我们的元数据过滤器只认英文括号 () 。解决方案：在查询前统一normalize字符串（ re.sub(r'[（）]', '()', query) ）。细节决定成败，真的。

6. 进阶能力：从知识问答到智能工作流的跨越

LlamaIndex的潜力远不止问答。当你吃透基础后，可以解锁三个高价值场景，让ROI翻倍。

6.1 自动化合同审查：把法务SOP编译成代码

传统合同审查靠人工逐条核对，LlamaIndex可将其自动化。核心是 结构化Node + 规则引擎 ：

# 将合同条款转为带规则的Node
contract_node = Document(
    text="甲方应在收到发票后30日内付款",
    metadata={
        "clause_type": "payment_term",
        "rule": "invoice_date + 30 days <= today",
        "penalty": "逾期每日0.05%违约金"
    }
)

# 查询时触发规则校验