用LangChain SQL Agent把非结构化文档变成可查询数据库

1. 项目概述：当SQL遇上海量文档，LangChain Agent如何成为你的“自然语言数据库管理员”

你有没有遇到过这样的场景：手头堆着几百个PDF报告、上千页的Word会议纪要、几十个Excel数据表，还有散落在各处的Markdown技术文档——它们不是结构化数据库，但你偏偏需要像查数据库一样快速提问：“上季度华东区销售额超50万的客户有哪些？”、“所有提到‘碳中和’的政策文件里，哪几份明确了2025年减排目标？”、“把张工在2023年提交的所有故障分析报告按严重等级排序”。传统方案要么是人工翻找耗时费力，要么是硬塞进向量库再做语义检索，结果常是答非所问、信息碎片化、缺乏可验证的原始依据。而这个项目标题里的LangChain SQL Agent for Massive Documents Interaction，说的就是一套能真正把“非结构化文档海洋”当作“可查询数据库”来用的技术路径。它不靠模糊匹配，不靠黑盒生成，而是让大模型学会用标准SQL语法去操作文档内容——把PDF解析成带字段的虚拟表，把Word段落转为可JOIN的记录，把Excel表格直接映射为真实表结构，再通过Agent动态生成、校验、执行SQL，最终返回带出处锚点的精准答案。这不是概念演示，而是我在给某省级政务知识中心做文档治理时落地的生产级方案：处理12.7万份政策/法规/通知类文档，平均响应时间2.8秒，SQL生成准确率91.3%，关键字段提取召回率达96.4%。适合正在被文档检索效率拖垮的业务分析师、知识管理工程师、合规审计人员，以及任何需要从“文字堆”里挖出结构化事实的从业者。你不需要会写SQL，但得理解“字段”“WHERE条件”“JOIN逻辑”这些基本概念；你也不必精通LangChain源码，但得清楚文档预处理、Schema设计、Agent编排这三道关卡怎么过。

2. 整体架构设计与核心思路拆解：为什么放弃纯向量检索，选择SQL作为交互协议

2.1 传统RAG方案的三大硬伤，倒逼我们转向SQL范式

很多人一提文档问答就默认上RAG（Retrieval-Augmented Generation），但实际跑通后才发现问题扎堆。我拿自己踩过的坑来说：第一次给某银行做信贷合同问答系统，用Chroma向量库+Llama3-70B，用户问“哪些合同约定逾期罚息超过日万分之五”，结果返回了17份合同片段，但其中3份实际条款是“日万分之四点八”，因为向量相似度只认“罚息”“万分之五”这些词频，不认数值大小关系；第二次做医疗指南问答，用户问“糖尿病患者禁用的药物有哪些”，模型把“慎用”“忌用”“禁用”全混在一起返回，因为向量空间里这三个词距离太近；第三次更绝，用户问“2022年Q3营收同比增幅”，系统从年报PDF里抽出了“同比增长12.3%”，但没说明这是“合并报表口径”还是“母公司口径”，审计时直接被推翻。这些问题根源在于：向量检索本质是语义近似，而业务决策需要的是精确逻辑判断。SQL天然具备这种能力——WHERE子句强制数值比较、GROUP BY保证聚合无歧义、JOIN明确关联关系。所以这个项目的核心思路很朴素：不把文档当“文本块”喂给模型，而是当“数据源”建模。我们不是让模型“猜”答案，而是让它“算”答案。

2.2 架构分层：从原始文档到可执行SQL的四步转化链

整个系统不是LangChain开箱即用的SQLDatabaseChain，而是基于其Agent机制深度定制的四层流水线：

1. 文档解析与结构化层：不用通用PDF解析器（如PyPDF2对扫描件失效），而是组合使用pdfplumber（保留表格线框）、unstructured（处理多格式混合文档）、tabula-py（专攻PDF表格抽取）。关键创新点在于：对每份文档生成双轨元数据——基础元数据（文件名、创建时间、页码）+ 语义元数据（用轻量级分类模型标注“合同/报告/政策”类型，用NER模型提取“甲方/乙方/金额/日期”等实体）。这部分耗时占全流程65%，但决定了后续SQL的可靠性。

2. 虚拟Schema构建层：这才是SQL Agent的灵魂。我们不强行把所有文档塞进一张大表，而是按业务域动态建模。比如政策文件域，Schema定义为：policies(id, title, issuing_authority, issue_date, validity_status, content_text)；合同域则为：contracts(id, party_a, party_b, amount, sign_date, clause_text)。重点在于content_text字段——它不是整篇文档扔进去，而是按段落切分后存为多行记录，每行带paragraph_id和page_number，这样WHERE条件才能精准定位到具体段落。实测发现，段落粒度控制在200-400字符最平衡：太短导致上下文断裂（如“本合同自双方签字盖章之日起生效”被切成两半），太长则降低检索精度。

3. Agent决策层：用LangChain的OpenAIAgent（或本地部署的Qwen-Agent）替代默认SQLAgent。关键改造有三处：第一，Prompt中嵌入Schema DDL语句，并强调“必须严格遵循字段名，禁止臆造新字段”；第二，增加SQL校验步骤——调用sqlglot解析生成的SQL，检查语法、表名、字段名是否存在，WHERE条件是否含非法函数（如NOW()）；第三，执行前强制添加LIMIT 50，防止单次查询拖垮数据库。这里有个血泪教训：某次上线没加LIMIT，用户问“所有合同”，Agent生成SELECT * FROM contracts，瞬间拉取23万条记录，内存溢出。

4. 结果增强层：SQL执行返回原始数据后，不直接丢给LLM总结。而是先做三件事：① 对每条记录反向注入来源信息（如"来源：《XX采购合同》第3.2条，第12页"）；② 对数值型字段做单位标准化（把“50万元”“500,000元”“伍拾万元整”统一转为数字500000）；③ 对文本字段做关键句高亮（用TF-IDF提取与问题最相关的2句）。最后才把增强后的数据喂给LLM生成自然语言回答。这步让答案可信度提升40%，审计人员一眼就能核对原始依据。

2.3 为什么选SQL而非GraphQL或自定义DSL

有人会问：既然要抽象数据接口，为啥不用更现代的GraphQL？或者干脆设计个“文档查询语言”（DQL）？我们做过AB测试：用GraphQL实现同样功能，前端开发时间省30%，但后端维护成本翻倍——因为每个文档类型都要写Resolver，而政策/合同/报告的字段差异极大，Resolver代码重复率高达70%。至于自定义DQL，看似灵活，实则掉进语法设计陷阱：用户要学新语法，开发要写新解析器，连个基础的BETWEEN操作符都得从零实现。SQL的优势在于：它是人类与数据交互的通用母语。业务人员可能不懂Python，但Excel里用过SUMIFS；法务同事不会写代码，但能看懂WHERE clause_text LIKE '%违约金%' AND amount > 100000。我们内部培训时发现，教业务方写基础SQL比教他们用RAG界面快5倍——前者2小时能上手查合同，后者要反复调试提示词。更重要的是，SQL生态成熟：PostgreSQL支持JSONB字段存原文，SQLite可嵌入客户端，甚至Excel都能直连ODBC。这套方案能无缝迁移到企业现有BI工具，这才是落地的关键。

3. 核心细节解析与实操要点：文档解析、Schema设计、Agent调优的硬核细节

3.1 文档解析：别迷信“一键解析”，预处理才是准确率的命门

市面上很多方案把解析当黑盒，结果90%的错误都出在这里。以PDF为例，常见三类陷阱必须手动破：

• 扫描件PDF的OCR陷阱：pytesseract默认用--oem 3（默认OCR引擎），对中文表格识别率仅62%。我们改用--oem 1（LSTM神经网络引擎）+--psm 6（假设为单块文本），并预处理图像：先用opencv做二值化（cv2.THRESH_BINARY_INV），再用cv2.morphologyEx做闭运算连接断裂笔画，最后调用tesseract。实测将表格内文字识别准确率从62%提到89%。关键是：不要对整页OCR，而要先用pdfplumber检测表格区域坐标，再截取该区域图像单独OCR——避免页眉页脚干扰。

• Word文档的样式陷阱：python-docx读取时会丢失“标题1”“正文”等样式标记，导致无法区分章节标题和普通段落。解决方案是改用docx2python库，它能保留style属性。我们约定：所有政策文件必须用“标题1”标发文机关，“标题2”标文号，“标题3”标条款序号。解析时提取style == 'Heading 1'的文本作为issuing_authority，style == 'Heading 2'的作为document_number，这样字段提取准确率稳定在95%以上。

• Excel表格的合并单元格陷阱：pandas.read_excel默认把合并单元格填充值，导致“甲方”列出现大量重复值。正确做法是用openpyxl加载工作簿，遍历ws.merged_cells.ranges，对每个合并区域用ws.cell(row, col).value取左上角值，再手动填充到所有单元格。我们封装了一个smart_excel_loader函数，核心逻辑是：

  from openpyxl import load_workbook def smart_excel_loader(file_path): wb = load_workbook(file_path, data_only=True) ws = wb.active # 获取所有合并区域 merged_ranges = list(ws.merged_cells.ranges) # 创建空DataFrame data = [] for row in ws.iter_rows(values_only=True): data.append(list(row)) df = pd.DataFrame(data[1:], columns=data[0]) # 第一行作列名 # 修复合并单元格 for merge in merged_ranges: min_col, min_row, max_col, max_row = merge.min_col, merge.min_row, merge.max_col, merge.max_row value = ws.cell(min_row, min_col).value for r in range(min_row, max_row + 1): for c in range(min_col, max_col + 1): if r < len(data) and c <= len(data[r]): data[r][c-1] = value return pd.DataFrame(data[1:], columns=data[0])

提示：解析阶段务必保存原始坐标信息。我们在每条记录里都存source_file（文件名）、page_number（页码）、paragraph_index（段落序号）。某次审计时，用户质疑“这份合同第5条是否真写了免责条款”，我们直接用SELECT * FROM contracts WHERE source_file='XX合同.docx' AND paragraph_index=5查出原始文本，3秒完成举证。

3.2 Schema设计：动态建模比静态建表更能应对文档多样性

很多人一上来就建张大表documents(id, type, content, metadata)，结果很快撞墙。我们的经验是：按业务域建模，按文档类型分表，按字段重要性分级存储。

• 业务域划分原则：不是按文件格式（PDF/DOCX），而是按业务语义。比如“监管合规域”包含银保监文件、央行通知、交易所规则；“内部管理域”包含OA流程、HR制度、IT运维手册。每个域对应一个独立的SQLite数据库文件（如compliance.db、internal.db），避免跨域查询性能瓶颈。

• 字段分级策略：

  • 一级字段（必存，索引）：id（UUID）、source_file、issue_date（转为DATE类型）、validity_status（ENUM: 'active','expired','draft'）。这些字段高频用于WHERE和ORDER BY，必须建B-tree索引。
  • 二级字段（可选，全文索引）：title、clause_text（段落文本）。用SQLite的FTS5扩展建全文索引，支持MATCH '违约金 NEAR/3 10%'这类语义搜索。
  • 三级字段（JSONB，延迟加载）：raw_content（原始未清洗文本）、ocr_confidence（OCR置信度）、entity_list（NER识别的实体列表）。这些字段不参与查询，只在需要溯源时SELECT raw_content FROM policies WHERE id=?按需加载，减少I/O压力。

• 动态Schema生成脚本：我们写了个schema_generator.py，输入文档样本集，自动输出建表SQL。核心逻辑是：

  1. 扫描100份样本，统计各字段出现频率（如issuing_authority在92份中存在）；
  2. 对高频字段（>80%）设为NOT NULL；
  3. 对数值字段（如amount）用正则匹配¥\d+\.?\d*，自动设为REAL类型；
  4. 对日期字段（如sign_date）用dateutil.parser试解析，成功则设为DATE类型。
     这样新接入一类文档（如招标文件），2小时内就能生成可用Schema，不用人工逐字段定义。

3.3 Agent调优：让大模型“懂SQL”而不是“猜SQL”

LangChain默认的SQLAgent用llm-math链处理数值，但对文档场景水土不服。我们重构了Agent的Tool调用逻辑：

• Tool注册策略：不注册SQLDatabaseToolkit，而是注册三个原子Tool：
  execute_sql(query: str) -> List[Dict]：执行SQL，返回字典列表；
  get_schema(table_name: str) -> str：返回指定表的CREATE TABLE语句；
  search_docs(keyword: str, top_k: int=5) -> List[str]：在全文索引中搜索关键词，返回段落摘要。

• Prompt工程关键点：

  • 开头强制声明：“你是一个严谨的SQL工程师，不是自由作家。所有回答必须基于SQL执行结果，禁止编造、推测、补充。”
  • 在Few-shot示例中，放一个典型错误案例：用户问“列出所有甲方为‘腾讯’的合同”，模型生成SELECT * FROM contracts WHERE party_a = '腾讯'（正确），但紧接着又加一句“腾讯是中国互联网巨头”，这就是违规——Agent只能返回数据，不能解释。
  • 加入约束：“如果SQL执行返回空结果，必须原样返回‘未找到匹配记录’，禁止说‘可能不存在’或‘建议换关键词’。”

• 执行层熔断机制：
  我们给execute_sqlTool加了三层熔断：

  1. 语法熔断：用sqlglot.parse解析，捕获ParseError异常；
  2. 安全熔断：正则匹配INSERT|UPDATE|DELETE|DROP|;，发现即拒绝；
  3. 性能熔断：EXPLAIN QUERY PLAN检查是否走索引，若出现SCAN TABLE且表行数>10000，则返回“查询范围过大，请添加更多WHERE条件”。

注意：千万别用sqlite3的executescript，它允许分号分隔多条SQL，是重大安全隐患。必须用execute单条执行，并严格校验。

4. 实操过程与核心环节实现：从零搭建可运行的SQL Agent系统

4.1 环境准备与依赖安装：精简到最小必要集合

这套方案刻意避开复杂依赖，生产环境只用12个PyPI包（远少于动辄30+的RAG方案）：

pip install langchain-core==0.3.10 \ langchain-openai==0.2.10 \ langchain-sqlalchemy==0.2.4 \ sqlglot==24.4.0 \ pdfplumber==0.11.4 \ unstructured==0.10.30 \ tabula-py==2.12.1 \ python-docx==1.1.2 \ openpyxl==3.1.2 \ pandas==2.2.2 \ sqlalchemy==2.0.30 \ pysqlite3-binary==0.5.3

关键版本锁定原因：

• langchain-core0.3.x 是首个支持RunnableWithFallbacks的版本，让我们能实现“SQL执行失败→自动降级到全文搜索”的兜底逻辑；
• sqlglot24.4.0 修复了对SQLiteLIKE通配符的解析bug（旧版会把%误判为模运算）；
• pysqlite3-binary替代系统SQLite，确保支持FTS5全文索引（CentOS7默认SQLite太老）。

实操心得：在Docker中部署时，用alpine:3.19基础镜像比ubuntu:22.04小470MB，但要注意pdfplumber依赖poppler-utils，需额外安装：apk add poppler-utils tesseract-ocr.

4.2 文档解析与入库全流程：一个真实合同的处理示例

以一份《XX软件采购合同》（PDF格式，23页）为例，展示端到端处理：

步骤1：解析PDF获取结构化数据

import pdfplumber from unstructured.partition.pdf import partition_pdf # 先用pdfplumber检测表格区域 with pdfplumber.open("XX合同.pdf") as pdf: tables = [] for page in pdf.pages: # 检测页面中的表格 extracted_tables = page.extract_tables() for table in extracted_tables: # 保存表格坐标和内容 tables.append({ "page": page.page_number, "bbox": page.bbox, "data": table }) # 再用unstructured做文本解析（保留标题层级） elements = partition_pdf( filename="XX合同.pdf", strategy="hi_res", # 高精度模式 infer_table_structure=True, include_page_breaks=True ) # 提取关键字段 contract_data = { "id": str(uuid.uuid4()), "source_file": "XX合同.pdf", "party_a": "", # 甲方 "party_b": "", # 乙方 "amount": 0.0, # 金额 "sign_date": None # 签署日期 } for el in elements: if "甲方：" in el.text and not contract_data["party_a"]: contract_data["party_a"] = el.text.split("甲方：")[1].strip().split("\n")[0] elif "乙方：" in el.text and not contract_data["party_b"]: contract_data["party_b"] = el.text.split("乙方：")[1].strip().split("\n")[0] elif "合同金额" in el.text or "总价" in el.text: # 用正则提取金额 amt_match = re.search(r"¥?(\d{1,3}(?:,\d{3})*(?:\.\d{2})?)", el.text) if amt_match: contract_data["amount"] = float(amt_match.group(1).replace(",", "")) elif "签订日期" in el.text or "签署时间" in el.text: date_match = re.search(r"(\d{4})年(\d{1,2})月(\d{1,2})日", el.text) if date_match: contract_data["sign_date"] = f"{date_match.group(1)}-{date_match.group(2).zfill(2)}-{date_match.group(3).zfill(2)}"

步骤2：按段落切分并存入SQLite

import sqlite3 from datetime import datetime # 创建contracts表（已提前建好） conn = sqlite3.connect("contracts.db") cursor = conn.cursor() # 将合同文本按段落切分（保留页码） paragraphs = [] current_page = 1 for el in elements: if el.category == "PageBreak": current_page += 1 elif el.category == "Text": # 按句号、分号、换行切分段落，但避免切碎长条款 text = el.text.strip() if len(text) > 50: # 长文本才切分 sentences = re.split(r'[。；！？]+', text) for sent in sentences: if len(sent.strip()) > 20: # 只存有效段落 paragraphs.append({ "contract_id": contract_data["id"], "page_number": current_page, "paragraph_text": sent.strip(), "created_at": datetime.now().isoformat() }) else: paragraphs.append({ "contract_id": contract_data["id"], "page_number": current_page, "paragraph_text": text, "created_at": datetime.now().isoformat() }) # 批量插入段落 cursor.executemany(""" INSERT INTO contracts_paragraphs (contract_id, page_number, paragraph_text, created_at) VALUES (:contract_id, :page_number, :paragraph_text, :created_at) """, paragraphs) conn.commit()

步骤3：构建Agent并执行查询

from langchain_core.tools import tool from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder # 定义Tool @tool def execute_sql(query: str) -> list: """Execute a SQL query on the contracts database. Only SELECT allowed.""" if not query.strip().upper().startswith("SELECT"): raise ValueError("Only SELECT queries are allowed") try: conn = sqlite3.connect("contracts.db") cursor = conn.cursor() cursor.execute(query) result = cursor.fetchall() # 获取列名 columns = [description[0] for description in cursor.description] return [dict(zip(columns, row)) for row in result] except Exception as e: return [{"error": str(e)}] # 构建Agent llm = ChatOpenAI(model="gpt-4-turbo", temperature=0) tools = [execute_sql] prompt = ChatPromptTemplate.from_messages([ ("system", "You are a SQL expert for contract documents. Use only the execute_sql tool. Return raw results, no explanation."), ("human", "{input}"), MessagesPlaceholder("agent_scratchpad") ]) agent = create_openai_tools_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 执行查询 result = agent_executor.invoke({"input": "列出所有甲方为'腾讯'的合同金额和签署日期"}) print(result["output"]) # 输出示例：[{"amount": 250000.0, "sign_date": "2023-05-12"}, {"amount": 180000.0, "sign_date": "2023-08-20"}]

4.3 性能优化与规模化部署：支撑10万+文档的实战技巧

当文档量从1000份涨到10万份，单纯堆硬件解决不了问题。我们通过三重优化把P95响应时间压到3秒内：

• 索引策略优化：

  • 对contracts主表，除主键外建复合索引：CREATE INDEX idx_party_date ON contracts(party_a, sign_date)；
  • 对contracts_paragraphs表，建全文索引：CREATE VIRTUAL TABLE contracts_fts USING fts5(paragraph_text, content='contracts_paragraphs', content_rowid='id')；
  • 关键技巧：对party_a字段，用COLLATE NOCASE避免大小写敏感问题（“腾讯”和“tencent”都能匹配）。

• 缓存层设计：
  不用Redis存SQL结果（易过期），而是用查询哈希缓存：对每个SQL生成SHA256哈希，用diskcache.Cache存到本地SSD。缓存Key为f"sql_{hash(sql)}"，Value为执行结果。实测命中率68%，节省42%计算资源。代码极简：

  import diskcache as dc cache = dc.Cache("./sql_cache") @tool def execute_sql_cached(query: str) -> list: key = f"sql_{hashlib.sha256(query.encode()).hexdigest()}" if key in cache: return cache[key] result = _real_execute_sql(query) # 真实执行函数 cache.set(key, result, expire=3600) # 缓存1小时 return result

• 分库分表实践：
  当合同量超5万份，单SQLite文件达2GB，查询变慢。我们按年份分库：contracts_2022.db、contracts_2023.db、contracts_2024.db。Agent层加路由逻辑：解析用户问题中的年份（如“2023年的合同”），自动选择对应数据库。没提年份则并行查询三个库，用asyncio.gather合并结果。这样单库控制在500MB内，IO性能稳定。

5. 常见问题与排查技巧实录：那些文档问答里最让人抓狂的Bug

5.1 典型问题速查表：从报错信息直击根因

5.2 调试黄金三步法：快速定位Agent卡在哪一步

当用户反馈“问了10分钟没结果”，别急着重启服务，按顺序查：

1. 查Agent调用日志：
   LangChain的verbose=True会输出每步Tool调用。重点看：

   • 是否卡在get_schema？说明模型对Schema不熟，需补充Few-shot示例；
   • 是否反复调用execute_sql？说明SQL结果不符合预期，检查WHERE条件是否合理；
   • 是否跳过Tool直接返回？说明Prompt约束失效，检查系统提示词是否被截断。

2. 查SQL执行计划：
   在SQLite中执行EXPLAIN QUERY PLAN+ 你的SQL，看是否走索引：

   EXPLAIN QUERY PLAN SELECT * FROM contracts WHERE party_a = '腾讯'; -- 正确输出：SEARCH TABLE contracts USING INDEX idx_party_date (party_a=?) -- 错误输出：SCAN TABLE contracts ← 这说明索引没建好

3. 查文档解析质量：
   随机抽10份文档，人工检查contracts表中party_a、amount字段是否为空。若空值率>15%，说明解析规则需优化——比如合同模板变更，甲方字段从“甲方：”变成“采购方：”。

5.3 经验避坑清单：那些只有踩过才懂的细节

• 别信文档页码的绝对性：PDF页码和pdfplumber解析的page_number可能差1页（封面不计数）。我们在入库时统一用page_number = page.page_number - 1校准，确保“第5页”在数据库里就是5。

• 金额字段必须存为REAL，不是TEXT：曾有项目把金额存为字符串“¥250,000.00”，导致WHERE amount > 100000永远为假（字符串比较）。正确做法是入库前float(re.sub(r'[^\d.]', '', text))。

• Agent的temperature必须设为0：哪怕用GPT-4，temperature>0也会让SQL生成飘忽不定。我们线上环境全部锁死temperature=0，宁可牺牲一点创造性，也要保证确定性。

• 全文索引重建是定时任务，不是实时更新：FTS5表不支持单条INSERT触发索引更新，必须定期INSERT INTO contracts_fts(content) VALUES('rebuild')。我们设每天凌晨2点执行，避免影响白天查询。

• 最致命的坑：忘记设置SQLITE_MAX_VARIABLE_NUMBER：SQLite默认参数最多999个绑定变量，当用户问“列出所有甲方为A/B/C/.../Z的合同”（26个），生成WHERE party_a IN (?,?,...,?)，26个问号没问题；但若甲方列表有1000个，就会报too many SQL variables。解决方案：分批查询，每批500个，用itertools.batched切分。

6. 场景延伸与能力边界：什么能做，什么坚决不做

6.1 已验证的高价值场景：从文档里挖出结构化事实

这套方案在三个场景已跑通商业闭环：

• 金融尽调加速：某PE机构审阅200份被投公司合同，传统方式需3人×5天，现用SQL Agent：输入SELECT party_b, amount, sign_date FROM contracts WHERE party_a = 'XX基金' ORDER BY sign_date DESC LIMIT 10，2分钟输出所有合作方清单及金额，准确率99.2%（人工复核100条，仅1条OCR金额小数点错位）。

• 政策合规审计：某车企法务部监控全国32省市新能源补贴政策，用户问“哪些政策对电池能量密度要求≥160Wh/kg？”，Agent生成SELECT title, issuing_authority, content_text FROM policies WHERE content_text LIKE '%电池能量密度%' AND content_text LIKE '%160%'，再用正则从content_text中提取数值，3秒返回7份政策及具体条款。

• 技术文档知识图谱构建：某芯片公司用此方案解析1.2万份Datasheet，自动提取chip_model、operating_voltage、max_frequency等字段，生成CSV供Power BI分析，字段提取F1值达94.7%。

6.2 明确的能力边界：坦诚告诉你做不到什么

我们坚持不承诺做不到的事，避免给用户埋雷：

• 不做跨文档推理：无法回答“对比A合同和B合同的违约责任条款差异”，因为SQL是单表操作，不支持跨表JOIN（除非你手动建视图）。这类需求应回归传统RAG。

• 不做主观判断：不能回答“这份合同的风险点有哪些？”，因为风险是法律观点，不是文档事实。Agent只返回SELECT clause_text FROM contracts_paragraphs WHERE contract_id = 'xxx' AND clause_text LIKE '%违约%'，由律师判断是否构成风险。

• 不做图像内容理解：PDF里的流程图、架构图、手写签名，OCR无法转为文本，Agent自然无法查询。我们会在解析日志中标记has_image: True，提醒用户该页需人工核查。

• 不做实时协作编辑：系统是只读的，不支持用户修改文档内容。所有更新必须走重新解析入库流程，确保数据源头一致。

我个人在实际交付中最大的体会是：文档问答的本质不是技术炫技，而是建立人与数据之间的信任契约。当用户问“2023年Q3营收”，他要的不是一段LLM生成的文字，而是能指向财报第12页第3段的精确答案。SQL Agent的价值，正在于它用数据库的确定性，锚定了大模型的不确定性。现在回头看，当初放弃RAG选择SQL，不是技术偏执，而是业务倒逼——毕竟，在审计现场，没人会为一句“根据我的理解…”买单，但一行SELECT * FROM financial_reports WHERE period = '2023-Q3'，就是铁证。