1. 这不是“调个API就完事”的玩具项目，而是一套可落地的私有知识服务系统

你手头有一堆PDF、Word、Excel、内部Wiki页面、甚至扫描件转成的文本——它们散落在不同系统里，新员工入职要花两周翻文档，客服每天重复回答“合同模板在哪”“报销流程第几步”，技术同事总在Slack里发“求一份XX接口的最新说明”。这时候，有人告诉你：“用LangChain+OpenAI做个Q&A Bot就行”，你信吗？我信，但前提是——你得清楚它到底在解决什么问题、为什么必须用这套组合、哪些环节一错全盘崩。这不是一个“复制粘贴几行代码就能跑通”的Demo，而是一套需要理解数据本质、模型边界、工程权衡的私有知识服务系统。核心关键词是： 私有文档、语义检索、上下文注入、LLM幻觉抑制、RAG流水线 。它不替代数据库，也不取代搜索框，而是补上“人知道问题、但不知道答案藏在哪份文档第几页”这个断点。适合三类人：技术负责人想快速验证知识中台可行性；一线工程师要给客户交付定制化问答能力；业务部门自己想搭个内部助手，又不敢把合同传到公有云。它不承诺“100%准确”，但能让你从“人工翻3小时”变成“3秒定位原文段落+生成口语化摘要”。下面所有内容，都来自我过去14个月在6个真实企业项目里踩过的坑、调过的参、重写的提示词——没有理论推演，只有哪一步卡了、为什么卡、怎么绕过去。

2. 整体架构设计：为什么必须是“检索+生成”双引擎，而不是单靠大模型记忆？

2.1 根本矛盾：大模型的“记性”和“诚实性”不可兼得

很多人第一反应是：“直接把所有文档喂给大模型微调不就行了？”——这是最危险的误区。我带过两个团队试过这条路：一个用Llama-3-8B在内部法律条款上LoRA微调，另一个用Qwen2-7B微调销售SOP。结果很一致：微调后模型对训练集内问题回答流畅，但一旦问“对比2023版和2024版退款政策差异”，它就开始编造条款编号、虚构审批节点。原因很物理：微调只是调整权重，不是真让模型“记住”原文。当问题超出训练分布，它会用概率最高但未必存在的token续写，这就是 幻觉（Hallucination） 。而私有文档问答的核心诉求恰恰是“零容错”——合同金额错一位、法规条款引错一条，后果远超技术故障。所以必须放弃“让模型背下来”的幻想，转向“让模型学会查资料”的路径。这正是RAG（Retrieval-Augmented Generation）的底层逻辑：把“记忆”交给向量数据库（可靠、可追溯），把“理解与表达”交给大模型（灵活、自然）。我们不是在造一个新模型，而是在造一套“图书管理员+文案编辑”的协作系统。

2.2 四层流水线：从原始文件到可信回答，每层都有不可妥协的硬约束

整个系统拆解为四个刚性层级，缺一不可，且每一层都存在明确的技术选型红线：

1. 文档预处理层 ：目标是把非结构化文本变成机器可读的“干净段落”。这里最大的陷阱是盲目信任PDF解析库。我见过三个项目栽在这：第一个用PyPDF2解析带表格的采购合同，表格内容全乱序；第二个用pdfplumber处理扫描件，OCR识别把“¥50,000”错成“¥50,0000”；第三个用Unstructured.io处理PPTX，把每页标题当独立文档切分，导致上下文断裂。解决方案不是换库，而是建立 双校验机制 ：先用pdfplumber做OCR（针对扫描件）或PyMuPDF做原生文本提取（针对可复制PDF），再用正则规则清洗——比如强制删除所有页眉页脚（匹配“第.*页.*共.*页”）、合并被换行切断的数字（“¥50,\n000”→“¥50,000”）、保留表格结构（用tabulate库重建为Markdown表格）。这一层输出必须是带元数据的文本块： {"content": "第三条 付款方式：...","source": "采购合同_v2.3.pdf","page": 7,"chunk_id": "contract_2024_007_3"} 。

2. 向量化与索引层 ：核心是让语义相似的文本在向量空间里挨得近。这里常犯的错是“以为Embedding模型越新越好”。我们实测过text-embedding-3-large、bge-m3、nomic-embed-text-v1.5在金融合同场景下的表现：text-embedding-3-large在长尾术语（如“反稀释条款”）召回率高但耗时翻倍；bge-m3对中文缩写（“NDA”“SLA”）理解更准；nomic在低资源设备上延迟稳定但精度略降。最终选择bge-m3，因为它的 多语言混合嵌入能力 能同时处理中英文混排的合资协议。关键参数是chunk_size：设256太碎，一个条款被切成三段，语义丢失；设1024太长，检索时噪声大。我们通过计算文档平均段落长度+标准差，定出 动态分块策略 ：法律文本用512，技术手册用384，会议纪要用256，并强制要求相邻块重叠128字符（避免切在句子中间）。索引工具选ChromaDB而非FAISS，因为Chroma支持元数据过滤（如 where={"source": "报销制度.docx"} ），而FAISS只能做向量近邻搜索。

3. 检索增强层 ：这是RAG防幻觉的“安全阀”。很多教程只教 similarity_search ，但真实场景需要三重过滤：

   • 相关性阈值过滤 ：设置 score_threshold=0.65 （bge-m3的余弦相似度），低于此值的片段直接丢弃，不进后续流程；
   • 来源多样性控制 ：同一文档最多取2个片段，避免答案被单份文件垄断；
   • 时效性加权 ：给元数据中的 last_modified 字段赋予权重，2024年文档的相似度分数×1.2，2022年文档×0.8。
     这一层输出不是“最像的3个片段”，而是 [{"content": "...", "score": 0.82, "source": "报销制度_2024.pdf", "page": 3}, ...] ，每个片段都带可审计的置信度。

4. 生成与后处理层 ：提示词（Prompt）不是“写得漂亮就行”，而是 结构化指令工程 。我们不用“请根据以下信息回答问题”，而是用XML标签强制模型分步思考：

   <INSTRUCTIONS>
   1. 严格基于提供的<CONTEXT>片段作答，禁止添加任何外部知识；
   2. 若<CONTEXT>中无直接答案，回答"未在提供的文档中找到相关信息"；
   3. 涉及数字、日期、条款编号等关键信息，必须原文引用，不得改写；
   4. 最终回答用中文，口语化，不超过150字。
   </INSTRUCTIONS>
   <CONTEXT>
   {retrieved_chunks}
   </CONTEXT>
   <QUESTION>
   {user_question}
   </QUESTION>
   

   这种结构让模型把“遵循指令”当作首要任务，而非追求回答长度。后处理环节加入 事实核查模块 ：用正则提取回答中的所有数字/日期/专有名词，反向匹配 片段，若发现未在上下文中出现的实体，自动触发重答。

2.3 为什么拒绝端到端微调？一次成本测算告诉你真相

有人问：“微调不是更‘懂’我们业务吗？”——我们做过精确成本核算。以10万页内部文档为例：

• RAG方案 ：向量化耗时约4.2小时（A10 GPU），索引存储占用28GB，每次查询平均延迟850ms（含网络+向量搜索+LLM生成）；
• 微调方案 ：准备数据集（清洗、标注、构造QA对）需3人×10天；LoRA微调耗时68小时（A100×2），显存占用峰值42GB；部署后单次推理延迟1.2秒，且无法动态更新知识（更新文档需重新微调）。
  更致命的是维护成本：RAG更新一份新合同，只需重新向量化该文件（2分钟）；微调方案更新，等于重启整个训练流程。在知识高频迭代的销售、法务、HR部门，这种敏捷性差距就是项目生死线。

3. 核心细节解析：从PDF解析到提示词，每个环节的魔鬼都在参数里

3.1 文档解析：别让第一道工序就埋下错误种子

PDF解析不是“打开文件读文本”那么简单。我们按文档类型建立了三级处理策略：

文档类型	推荐工具	关键参数配置	常见陷阱与修复
可复制PDF（文字型）	PyMuPDF (fitz)	page.get_text("blocks") + sort=True	默认排序会打乱图文混排顺序；必须用 sort=True 按坐标重排，否则“图1：流程图”出现在“步骤3”后面
扫描件PDF（图像型）	pdfplumber + PaddleOCR	ocr=True , ocr_languages=["ch_sim","en"]	OCR对小字号（<8pt）识别率骤降；需预处理：用OpenCV二值化+去噪，再送OCR
PPTX/PPT	python-pptx	slide.shapes 遍历+ text_frame.text 提取	自动动画文本框会被忽略；必须遍历 shape.text_frame.paragraphs 并合并所有段落

实操中，我们发现83%的“回答错误”根源在解析层。典型案例如下：

• 案例1：财务报表PDF
  原始PDF中“应收账款”和“应付账款”在同一行用不同字体显示，PyPDF2将其识别为“应收账款应付账款”，导致向量化后两概念语义混淆。修复：用PyMuPDF的 get_text("words") 获取每个词的坐标，按Y轴分组，再按X轴排序，重建表格结构。
• 案例2：带水印的扫描合同
  PaddleOCR将半透明水印“CONFIDENTIAL”误识为正文，污染向量空间。修复：在OCR前用OpenCV检测高频水印区域（用形态学操作提取重复纹理），对该区域做像素级遮盖。

提示：永远保存原始解析日志。我们要求每个文档解析后生成 {filename}_debug.json ，包含原始文本、清洗后文本、分块结果、各块向量均值。当用户反馈“为什么没找到XX条款”，直接查日志比重跑流程快10倍。

3.2 向量嵌入：选模型不如懂数据，bge-m3的隐藏参数实战

bge-m3之所以在中文场景胜出，关键在于它的 多粒度嵌入（Multi-Granularity Embedding） 能力。它不只输出一个向量，而是为同一文本生成：

• dense ：传统稠密向量，用于语义相似度计算；
• sparse ：稀疏向量（类似BM25），捕捉关键词权重；
• colbert ：细粒度向量，对短语匹配更敏感。

我们实际使用的是 dense+sparse 融合检索。具体实现：

# ChromaDB中启用混合检索
collection.query(
    query_texts=[question],
    n_results=5,
    # dense权重0.7，sparse权重0.3
    where={"source": {"$in": allowed_sources}},
    include=["documents", "metadatas", "distances"]
)
# 后处理：对每个结果计算融合得分 = 0.7 * dense_score + 0.3 * sparse_score

参数调优上，有两个反直觉发现：

• normalize_embeddings=True 必须开启 ：否则不同长度文本的向量模长差异巨大，短文本（如“NDA”）在余弦相似度计算中天然吃亏；
• batch_size=16 比32更稳 ：bge-m3在batch>16时会出现梯度溢出，导致部分向量异常（模长接近0），我们在日志中加入 np.linalg.norm(vector) 校验，异常向量自动重算。

注意：不要迷信“更大模型更好”。我们测试过text-embedding-3-large在合同场景的召回率仅比bge-m3高1.2%，但向量化耗时增加220%，GPU显存占用翻倍。在企业级部署中， 延迟和成本是比0.1%精度更重要的指标 。

3.3 检索优化：不是“找最像的”，而是“找最可信的”

单纯用相似度排序会出大问题。比如用户问：“离职补偿金怎么算？”，检索可能返回：

• 片段A（相似度0.85）：“员工主动辞职，公司不支付补偿金”（来自《劳动合同法》解读）；
• 片段B（相似度0.79）：“协商解除劳动合同，公司应支付N+1”（来自《员工手册》第5.2条）。

如果只取Top3，B可能被A挤掉，但B才是公司执行依据。因此我们引入 元数据加权重排序 ：

# 对每个检索结果计算综合得分
def calculate_score(chunk, query):
    base_score = chunk["distance"]  # Chroma返回的是距离，越小越好
    # 来源权威性加权：手册>制度>通知>邮件
    source_weight = {"员工手册": 1.5, "管理制度": 1.2, "通知": 0.8, "邮件": 0.5}
    weight = source_weight.get(chunk["source_type"], 1.0)
    # 时效性加权：2024年文档×1.3，2023年×1.0，2022年×0.7
    year_weight = max(0.7, 1.0 + (2024 - int(chunk["year"])) * 0.3)
    return base_score * weight * year_weight

这个公式让《员工手册》中2024年的条款，即使相似度略低，也能排到前面。更重要的是，它把业务规则（谁制定的、何时生效）编码进了技术流程，让技术决策可解释、可审计。

3.4 提示词工程：用结构化XML代替自由发挥，降低模型“自由发挥”空间

我们废弃了所有“请友好回答”“请简洁明了”这类模糊指令。真正的提示词是带约束的程序：

<SYSTEM>
你是一个严谨的文档助理，只根据提供的<CONTEXT>回答<QUESTION>。
</SYSTEM>
<CONTEXT>
{context_chunks}
</CONTEXT>
<QUESTION>
{question}
</QUESTION>
<OUTPUT_FORMAT>
1. 开头用【答案】标记；
2. 若<CONTEXT>中有直接答案，用原文关键句+口语化解释；
3. 若<CONTEXT>中无答案，严格输出【未在提供的文档中找到相关信息】；
4. 禁止使用“可能”“大概”“通常”等模糊词汇；
5. 所有数字、日期、条款编号必须原文照搬。
</OUTPUT_FORMAT>

为什么有效？因为大模型对XML标签的遵循率远高于自然语言指令。我们做过AB测试：用自然语言提示词，幻觉率12.7%；用XML结构化提示词，幻觉率降至3.1%。关键在 <OUTPUT_FORMAT> 的强制格式——模型会优先满足格式要求，再考虑内容。实操中，我们还加入 温度（temperature）控制 ：生成时设 temperature=0.1 （而非默认0.7），进一步压缩随机性。但注意：温度不能设0，否则模型会陷入死循环（如反复输出“根据文档”却不继续）。

实操心得：提示词不是写一次就完事。我们建立“提示词灰度发布”机制：新提示词先对5%流量生效，监控“未找到信息”率、平均回答长度、人工抽检准确率，达标后再全量。曾有一个提示词让“未找到信息”率从8%飙升到35%，排查发现是 <CONTEXT> 标签名和实际传入变量名不一致，模型直接跳过上下文。

4. 实操全流程：从零搭建一个可运行的私有文档问答系统

4.1 环境准备与依赖安装：避开Python包版本地狱

我们锁定以下环境组合，经6个项目验证无兼容问题：

• Python 3.10.12（避免3.11+的asyncio变更影响LangChain）
• LangChain 0.1.18（0.2.x版本重构了DocumentLoader，大量旧代码失效）
• ChromaDB 0.4.24（0.5.x移除了 get_or_create_collection ，需手动处理集合存在性）
• PyMuPDF 1.23.23（新版对中文PDF渲染有偏移）

安装命令必须带版本锁：

pip install "langchain==0.1.18" "chromadb==0.4.24" "pymupdf==1.23.23" \
"unstructured[all]==0.10.25" "paddlepaddle-gpu==2.6.1" \
"openai==1.35.11" "tiktoken==0.6.0"

警告：不要用 pip install langchain ！LangChain生态包名混乱，“langchain”是旧版，“langchain-core”“langchain-community”是新版拆分包。我们坚持用0.1.x系列，因其API稳定，文档齐全，社区问题可查。

4.2 文档加载与预处理：一个函数搞定90%的脏数据

核心函数 load_and_chunk_documents() 封装了所有解析逻辑：

def load_and_chunk_documents(file_paths: List[str]) -> List[Document]:
    documents = []
    for file_path in file_paths:
        try:
            # 根据扩展名选择loader
            if file_path.endswith(".pdf"):
                loader = PyMuPDFLoader(file_path) if is_text_pdf(file_path) else PDFPlumberLoader(file_path)
            elif file_path.endswith((".docx", ".pptx")):
                loader = Docx2txtLoader(file_path) if file_path.endswith(".docx") else UnstructuredPowerPointLoader(file_path)
            else:
                loader = TextLoader(file_path, encoding="utf-8")
            
            docs = loader.load()
            # 清洗：删除页眉页脚、合并断行、标准化空格
            cleaned_docs = [clean_text(doc.page_content) for doc in docs]
            # 分块：按文档类型动态设置chunk_size
            chunk_size = get_optimal_chunk_size(file_path)
            text_splitter = RecursiveCharacterTextSplitter(
                chunk_size=chunk_size,
                chunk_overlap=128,
                separators=["\n\n", "\n", "。", "！", "？", "；", "，", " "]
            )
            chunks = text_splitter.create_documents(cleaned_docs, metadatas=[{"source": file_path}]*len(cleaned_docs))
            documents.extend(chunks)
        except Exception as e:
            logger.error(f"Failed to process {file_path}: {str(e)}")
            continue
    return documents

其中 clean_text() 函数是关键：

def clean_text(text: str) -> str:
    # 删除页眉页脚（匹配"第.*页.*共.*页"或"©.*公司"）
    text = re.sub(r"第\s*\d+\s*页\s*共\s*\d+\s*页", "", text)
    text = re.sub(r"©\s*[\u4e00-\u9fa5a-zA-Z0-9\s]+", "", text)
    # 合并被换行切断的数字和单位
    text = re.sub(r"(\d+),\s*\n(\d+)", r"\1,\2", text)  # "1, \n000" → "1,000"
    text = re.sub(r"(\d+)\s*\n(元|万元|USD|CNY)", r"\1\2", text)  # "500 \n元" → "500元"
    # 标准化空格和换行
    text = re.sub(r"\s+", " ", text).strip()
    return text

这个函数让90%的文档无需人工干预即可进入后续流程。剩下的10%（如加密PDF、损坏PPTX）会记录在 error_log.csv 中，供业务方确认是否需人工处理。

4.3 向量存储与检索：ChromaDB的生产级配置

本地开发用 ChromaDB 内存模式，但生产必须用持久化+客户端模式：

# 生产环境：启动ChromaDB服务
# docker run -d -p 8000:8000 --name chroma -e CHROMA_DB_IMPL="duckdb+parquet" -e CHROMA_PERSIST_DIRECTORY="/data" -v $(pwd)/chroma_data:/data chromadb/chroma

from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceBgeEmbeddings

# 初始化嵌入模型（bge-m3）
embeddings = HuggingFaceBgeEmbeddings(
    model_name="BAAI/bge-m3",
    model_kwargs={"device": "cuda"},
    encode_kwargs={"normalize_embeddings": True},
    query_instruction="为这个句子生成表示以用于检索相关文章："
)

# 连接远程ChromaDB
vectorstore = Chroma(
    collection_name="private_docs",
    embedding_function=embeddings,
    client_settings=Settings(
        chroma_server_host="localhost",
        chroma_server_http_port="8000",
        anonymized_telemetry=False
    )
)

# 加载文档到向量库
vectorstore.add_documents(documents)

关键配置说明：

• encode_kwargs={"normalize_embeddings": True} ：确保向量模长为1，相似度计算稳定；
• query_instruction ：bge-m3要求查询时加指令前缀，否则检索质量下降；
• client_settings ：禁用遥测，符合企业数据合规要求。

实操技巧：首次加载10万页文档时，ChromaDB会卡在 persist 阶段。解决方案是分批提交： vectorstore.add_documents(documents[i:i+1000]) ，每批后 time.sleep(0.1) ，避免内存溢出。

4.4 RAG链构建：LangChain的Chain不是银弹，要亲手缝合

我们不用 RetrievalQA 这种黑盒链，而是手动组装可调试的组件：

from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate
from langchain_openai import ChatOpenAI

# 定义提示词模板
prompt_template = """<SYSTEM>你是一个严谨的文档助理...</SYSTEM>
<CONTEXT>{context}</CONTEXT>
<QUESTION>{question}</QUESTION>
<OUTPUT_FORMAT>...</OUTPUT_FORMAT>"""

PROMPT = PromptTemplate(
    template=prompt_template,
    input_variables=["context", "question"]
)

# 初始化LLM（OpenAI API）
llm = ChatOpenAI(
    model_name="gpt-4-turbo",
    temperature=0.1,
    max_tokens=512,
    openai_api_key="your-key",
    openai_api_base="https://api.openai.com/v1"  # 企业可替换为自建代理
)

# 构建RAG链
rag_chain = (
    {
        "context": vectorstore.as_retriever(
            search_kwargs={
                "k": 5,
                "filter": {"source_type": {"$in": ["员工手册", "管理制度"]}}  # 元数据过滤
            }
        ),
        "question": RunnablePassthrough()
    }
    | PROMPT
    | llm
    | StrOutputParser()
)

这个链的关键在于：

• search_kwargs 中 filter 参数实现业务规则过滤；
• RunnablePassthrough() 确保问题原样传入，不被中间组件修改；
• StrOutputParser() 强制输出字符串，避免LangChain自动包装成 AIMessage 对象。

测试时，我们用 rag_chain.invoke("试用期工资怎么发？") 直接调用，返回纯文本答案，方便前端集成。

4.5 部署与监控：让Bot不止于Demo，而成为可用的服务

生产部署采用FastAPI+Uvicorn：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="Private Docs Q&A API")

class QueryRequest(BaseModel):
    question: str
    sources: List[str] = None  # 可选：限定检索来源

@app.post("/ask")
async def ask_question(request: QueryRequest):
    try:
        # 动态设置检索器
        retriever = vectorstore.as_retriever(
            search_kwargs={"k": 3}
        )
        if request.sources:
            retriever = vectorstore.as_retriever(
                search_kwargs={"k": 3, "filter": {"source": {"$in": request.sources}}}
            )
        
        # 调用RAG链
        answer = rag_chain.invoke({"question": request.question})
        
        # 记录审计日志
        log_entry = {
            "timestamp": datetime.now().isoformat(),
            "question": request.question,
            "answer": answer,
            "sources_used": [c.metadata["source"] for c in retriever.get_relevant_documents(request.question)[:2]]
        }
        audit_logger.info(json.dumps(log_entry))
        
        return {"answer": answer}
    except Exception as e:
        audit_logger.error(f"Error processing {request.question}: {str(e)}")
        raise HTTPException(status_code=500, detail="Internal server error")

监控指标必须包含：

• 检索命中率 ： len(retriever.get_relevant_documents(q)) > 0 的比例，低于95%需检查向量化质量；
• 幻觉率 ：人工抽检100个回答，统计“答案中出现未在 中出现的实体”次数；
• P95延迟 ：超过1.5秒需告警，排查向量搜索或LLM调用瓶颈。

我们用Grafana看板实时展示这三项指标，当幻觉率突增时，自动触发提示词回滚到上一稳定版本。

5. 常见问题与排查技巧：那些文档里不会写的血泪经验

5.1 “为什么我的Bot总是胡说八道？”——幻觉根因排查树

幻觉不是随机发生，而是有迹可循。我们总结出四层排查树，按顺序检查：

层级	检查项	判定方法	解决方案
L1：检索层失效	检索返回的片段是否真的包含答案？	手动执行 retriever.get_relevant_documents("问题") ，查看返回内容	① 调低 score_threshold ；② 检查文档解析是否漏掉关键段落；③ 用 bge-m3 的 colbert 模式重试
L2：上下文截断	返回的片段是否被 chunk_size 切碎？	查看 <CONTEXT> 中是否有完整句子被切断（如“根据第5.2条，”在片段末尾）	减小 chunk_overlap 至128，或改用 SemanticChunker （基于句子相似度分块）
L3：提示词失效	模型是否忽略指令？	将 temperature 设为0，观察是否仍编造答案	改用XML结构化提示词；增加 <OUTPUT_FORMAT> 强制格式；在 <CONTEXT> 中插入干扰文本测试模型是否真在读
L4：LLM固有缺陷	问题本身是否超出模型能力？	用相同提示词问公开知识（如“北京人口多少？”），若也编造，则换模型	换用 gpt-4-turbo 或 claude-3-haiku ；对数字类问题，加后处理：用正则提取回答中所有数字，反查

实操案例：某银行项目上线后幻觉率22%。按树排查：L1发现检索返回的“贷款利率”片段只有“年化4.2%”，缺失“LPR加点”部分；L2发现 chunk_size=512 把“LPR基准利率+加点120BP”切在两块；调整 chunk_size=384 + overlap=128 后，幻觉率降至4.3%。

5.2 “为什么PDF里的表格全乱了？”——表格解析的终极方案

表格是PDF解析的阿喀琉斯之踵。我们的方案是 三层防御 ：

1. 预检测 ：用PyMuPDF的 page.get_drawings() 检测是否存在表格线框；
2. 主解析 ：若有线框，用 pdfplumber 的 extract_tables() ；若无线框，用 camelot-py 的 Lattice 模式（基于线条）；
3. 后校验 ：用 pandas.DataFrame.equals() 比对原始表格图片（截图）与解析结果，差异>15%则标记为“高风险表格”，人工复核。

关键代码：

def extract_table_from_page(page):
    # 检测线框
    drawings = page.get_drawings()
    if len(drawings) > 5:  # 粗略判断有表格线
        tables = page.extract_tables(table_settings={"vertical_strategy": "lines", "horizontal_strategy": "lines"})
    else:
        # 无线框，用文字位置聚类
        words = page.get_text("words")
        # 按Y坐标分组（行），X坐标排序（列）
        rows = group_words_by_y(words, threshold=5)
        table_data = [sorted(row, key=lambda w: w[0]) for row in rows]
        return table_data
    return tables

5.3 “为什么有些文档向量化后搜不到？”——向量空间塌陷诊断

当某份文档完全无法被检索到，大概率是向量空间塌陷。诊断步骤：

1. 取该文档一个典型段落，用 embeddings.embed_query() 获取向量；
2. 计算该向量与自身点积（即模长平方），若<0.1，说明向量几乎为零；
3. 检查该段落是否全是标点、空格、或特殊字符（如PDF导出的乱码“”）；
4. 在 clean_text() 中加入 re.sub(r"[^\u4e00-\u9fa5a-zA-Z0-9\u3000-\u303f\uff00-\uffef\s]", "", text) 清除不可见字符。

我们遇到过最诡异的案例：某份Word文档用WPS导出PDF，中文字符被编码为 0xE2 0x80 0x9C （左双引号）， bge-m3 将其视为乱码，向量模长趋近于0。解决方案：在清洗阶段用 text.encode('utf-8').decode('utf-8', errors='ignore') 强制清理。

5.4 “如何让Bot回答更‘像人’？”——业务语感调优的3个野路子

技术准确只是底线，业务部门要的是“像老员工一样回答”。我们用三个非技术手段调优：

• 语料注入 ：收集100条历史客服对话，提取“用户问法-标准答案”对，作为Few-shot示例插入提示词；
• 语气词控制 ：在 <OUTPUT_FORMAT> 中加入“回答开头可加‘好的，’‘明白了，’等礼貌用语，但不得超过5个字”；
• 否定表达统一 ：业务规定“不”“未”“不可”必须统一为“不”，在后处理中用 re.sub(r"(未|不可|禁止)", "不", answer) 强制替换。

这些细节让业务方满意度从62%提升到89%，因为他们听到的不再是“根据文档第3.2条”，而是“不，试用期工资必须按全额发放”。

5.5 性能瓶颈速查表：当响应慢于2秒时，立刻对照

现象	可能原因	快速验证命令	解决方案
首次查询慢（>5s）	ChromaDB首次加载索引	docker exec -it chroma ls -lh /data 查看索引文件大小	增加 chroma 容器内存限制至4GB；预热：启动时执行一次空查询
持续高延迟（>1.5s）	向量搜索慢	time python -c "from chromadb.api import Client; c=Client(); c.get_collection('private_docs').count()"	检查 collection.count() 是否正常；若卡住，重启ChromaDB
LLM调用超时	OpenAI API限流	curl -H "Authorization: Bearer YOUR_KEY" https://api.openai.com/v1/models	检查API Key配额；切换到 gpt-3.5-turbo 备用模型；增加 max_retries=3
CPU飙高100%	PDF解析阻塞	top -p $(pgrep -f "pymupdf")	限制并发： concurrent.futures.ThreadPoolExecutor(max_workers=2)

这张表贴在我们每个项目的监控看板旁，运维同学5分钟内能定位80%的性能问题。

我在实际交付中发现，最常被低估的不是技术难度，而是 业务规则的颗粒度 。比如“报销制度”里一句“特殊情况可特批”，技术上要定义“特殊情况”有哪些枚举值、谁有审批权、需要什么附件——这些必须由业务方签字确认，写进元数据过滤规则。技术可以跑得飞快