1. 项目概述：让大模型“认得”你刚写完的代码库，不是玄学，是工程闭环

“如何让主流的大模型支持自己新写的库？”——这句话一出来，我立刻在脑子里过了一遍过去三年里被问爆的二十多个类似问题：有刚用 Rust 写完一个轻量级 JSON Schema 验证器的后端同学，发来截图问“为什么 Qwen3 看不懂我 README 里的 validate_with_context() 接口”；有做教育 SaaS 的团队，自研了一套 Python 的动态题干生成引擎，但 Copilot 总是补出 import sympy 而不是他们封装好的 from eduengine.gen import render_question ；还有位硬件工程师，用 C++ 和 Python bindings 做了个嵌入式设备通信协议栈，结果本地部署的 Llama-3-70B-Instruct 在写 demo 脚本时，连函数名都拼错成 send_packet_v2() 而不是真实的 send_frame() 。

这根本不是“大模型不聪明”，而是我们混淆了两个完全不同的概念： 模型的推理能力 （inference capability）和 模型的知识覆盖边界 （knowledge boundary）。主流闭源模型（如 GPT-4o、Claude-3.5-Sonnet）和开源大模型（如 Qwen3、Llama-3、DeepSeek-V3）在训练完成后，其权重就已固化，它“知道”的所有 API、类名、参数签名、错误码、典型用法，全部来自训练截止日（通常是 2023 年底至 2024 年中）之前公开可爬取的代码仓库、文档网站、Stack Overflow 帖子和 GitHub Issues。你昨天刚 git init 的那个 my-awesome-utils 库，对它而言，物理上不存在。

所以，“让大模型支持你的新库”，本质不是去改模型本身（那需要重训或全量微调，成本动辄百万美元级 GPU 小时），而是构建一条 从你的代码资产到模型上下文的高效、稳定、低损耗的信息通路 。这条通路有且仅有三种工业级可行路径： RAG（检索增强生成）用于实时问答与文档理解、工具调用（Tool Calling）用于精准执行、以及轻量级 LoRA 微调用于深度行为对齐 。本文不讲理论，只讲我在给 7 家不同技术栈公司落地这三类方案时，踩过的坑、算过的账、压测过的吞吐、以及最终写进 SOP 的实操清单。你不需要懂 Transformer 架构，但必须清楚：什么时候该用 RAG，什么时候必须上 Tool Calling，什么时候微调才是唯一解——这个判断，直接决定你两周还是两个月才能让销售同事拿着 demo 给客户演示“我们的 SDK 已被大模型原生支持”。

核心关键词已在前 100 字内自然出现： RAG、工具调用、LoRA 微调、知识覆盖边界、模型上下文、SDK 支持、代码资产、工业级落地 。这篇文章适合三类人：一是刚完成 MVP 开发、正准备做开发者生态建设的初创技术负责人；二是负责内部 AI 编程助手建设的平台工程团队；三是想把自研库接入 Copilot / CodeWhisperer / 通义灵码等商业 IDE 插件的资深工程师。它不教你从零训练模型，但能让你在 48 小时内，让 GPT-4o 准确调用你库里的 parse_config() 函数，并返回符合你文档定义的 JSON Schema 错误提示。

2. 方案选型逻辑：为什么不是“全都要”，而是“必须三选一”？

2.1 三种路径的本质差异与适用场景红线

很多人一上来就想“三管齐下”：既做 RAG 又接 Tool Calling 还要微调。我见过最典型的失败案例，是一家做金融风控规则引擎的公司，花了 6 周时间同时推进三件事，最后发现：RAG 返回的文档片段太长，触发了模型 context window 限制，导致生成代码时漏掉关键参数；Tool Calling 的 schema 定义没处理好枚举值校验，用户输错 mode="batch" （正确应为 "stream" ），模型直接静默失败；而微调用的 200 条合成数据，90% 是人工编造的“理想调用”，上线后真实用户提问全是“怎么在异步任务里重试失败的 rule_set？”——模型完全不会答。

根本原因在于，这三条路径解决的是 不同层级、不同延迟要求、不同精度目标的问题 ，强行混合只会制造新的耦合点和故障面。下面这张表，是我根据 12 个真实项目压测数据整理的决策矩阵，它比任何理论描述都更直接：

维度	RAG（检索增强生成）	Tool Calling（工具调用）	LoRA 微调（低秩适配微调）
核心目标	让模型“读懂”你的文档和示例	让模型“精确执行”你的函数	让模型“像你团队的资深成员一样思考”
响应延迟	中（需检索+重排+生成，P95 ≈ 1.8s）	低（仅模型推理+一次函数调用，P95 ≈ 0.4s）	极低（纯推理，P95 ≈ 0.15s）
知识更新时效性	秒级（文档变更 → 向量库更新 → 即时生效）	秒级（函数签名变更 → Tool Schema 更新 → 即时生效）	小时级（需重新训练+部署新模型实例）
对模型能力依赖	高（严重依赖模型的阅读理解与摘要能力）	中（依赖模型的指令遵循与参数提取能力）	低（模型只需具备基础语言建模能力）
开发复杂度	中（需搭建向量库、分块策略、重排模型）	高（需精确定义 OpenAPI Schema、处理异步/流式、错误回传）	极高（需数据构造、训练 pipeline、评估体系）
典型失败场景	检索到错误文档片段；模型过度概括丢失细节	用户输入模糊，模型无法准确映射到工具；工具执行报错无反馈	微调数据偏差导致模型在未见场景下胡说八道

提示：这不是选择题，而是“诊断题”。请先回答三个问题：

1. 用户最常问的是“这个功能怎么用？”（→ RAG）
2. 用户最常做的是“帮我生成一个调用 xxx() 的脚本”（→ Tool Calling）
3. 用户最常卡住的是“为什么我的 xxx() 在分布式环境下会丢数据？有没有最佳实践？”（→ LoRA 微调）
   90% 的项目，只需专注做好其中一项，就能覆盖 85% 的用户需求。

2.2 为什么 RAG 是绝大多数项目的起点和基石？

我坚持认为，RAG 是所有“让大模型支持新库”项目的默认启动项，原因非常务实： 它不修改模型，不增加服务链路，不引入新故障点，且效果立竿见影 。去年帮一家做 IoT 设备管理平台的客户落地时，他们自研的 device-sdk-python 有 47 个核心类、129 个方法，文档分散在 Sphinx、GitHub Wiki 和 3 个内部 Confluence 页面。我们只做了三件事：

1. 用 sphinx-autobuild 导出所有 .rst 源文件；
2. 用 langchain.text_splitter.RecursiveCharacterTextSplitter 按代码块（```python）和标题（===）两级切分，chunk_size=300，overlap=50；
3. 用 bge-m3 模型将所有 chunk 向量化，存入 ChromaDB（单机版，内存占用 < 1.2GB）。

整个过程耗时 3.5 小时，部署后，当用户在 Web UI 输入“如何批量升级 100 台设备的固件？”，系统检索到 DeviceManager.batch_firmware_upgrade() 方法的完整 docstring 和两个真实调用示例，模型据此生成的代码，第一版就通过了他们 80% 的单元测试。没有微调，没有新 API，就是纯粹的“让模型看到你写的字”。

但 RAG 的陷阱也极深。最常见的误区是“扔文档就完事”。我亲眼见过团队把整本 PDF 格式的 API 手册（200 页）直接喂给向量化模型，结果模型检索到的永远是第 12 页的“概述”，而不是第 87 页的 retry_policy 参数说明。 RAG 的效果，70% 取决于分块策略，20% 取决于重排模型，10% 才是向量模型本身 。后面章节会详解我们自研的“代码优先分块法”（Code-First Chunking），它能让 Python SDK 的检索准确率从 58% 提升到 92%。

2.3 Tool Calling：当“生成代码”变成“执行代码”，精度跃迁的关键一跳

RAG 解决的是“理解”，Tool Calling 解决的是“行动”。它的价值，在于把模型从“文字游戏选手”升级为“可编程代理”。当你看到用户提问“用我的 data-validator 库，校验这份 CSV 并标出所有邮箱格式错误”，RAG 只能返回 validate_csv(file_path, rules) 的用法说明；而 Tool Calling 能直接调用这个函数，传入用户上传的 CSV 文件，拿到结构化错误列表，再由模型用自然语言总结：“共发现 3 处错误：第 5 行邮箱缺少 @ 符号，第 12 行域名后缀非法”。

但这一步的工程门槛陡然升高。最大的坑在于 OpenAPI Schema 的定义精度 。很多团队直接用 pydantic.BaseModel.schema_json() 生成 JSON Schema，但忽略了几个致命细节：

• Optional[str] 在 Schema 中生成 "type": ["string", "null"] ，但模型有时会生成 "value": null ，而你的函数实际接收的是 None ，类型检查直接失败；
• 枚举值（ Literal["json", "csv", "xml"] ）若未在 Schema 的 enum 字段显式列出，模型大概率会瞎猜一个 "yaml" ；
• 对于接受 Path 或 BytesIO 类型的参数，Schema 必须明确标注 format: binary 并提供 description 说明“此参数为用户上传的文件二进制流”。

我们最终沉淀出一套 tool-schema-gen 工具链，它会扫描你的函数签名，自动注入这些工业级必需字段。例如，对一个接收文件的函数：

def validate_csv(file: bytes, rules: List[Rule]) -> ValidationResult:
    """校验 CSV 文件，返回结构化结果"""

它生成的 Schema 片段会强制包含：

"file": {
  "type": "string",
  "format": "binary",
  "description": "用户上传的 CSV 文件原始字节流（非路径）"
}

注意：Tool Calling 不是万能的。它要求你的函数必须是 纯计算、无副作用、确定性输出 。如果你的库需要连接数据库、调用外部 HTTP API 或读写本地磁盘，就必须在 Tool Wrapper 层做严格隔离和沙箱化。我们曾因一个未加锁的全局缓存变量，导致并发调用时返回了其他用户的校验结果——这种 bug 在日志里几乎不可见，只能靠混沌工程压测暴露。

2.4 LoRA 微调：当你的库有“灵魂”，而不仅是“接口”

LoRA 微调是三者中投入最大、周期最长、但也最彻底的方案。它适用于一种特殊场景： 你的库承载了一套独特的领域逻辑、设计哲学或隐式约定，这些无法通过文档或函数签名穷尽表达 。比如，一家做合规审计软件的公司，其核心库 audit-engine 有一条铁律：“所有 check_*() 函数，若发现高危问题，必须立即中断执行并返回 AuditResult(status='fail', critical=True) ，绝不允许继续检查低危项”。这条规则写在内部 Wiki 第 37 页，但 RAG 检索不到（因为没人会搜“中断执行”），Tool Calling 也无法编码（因为它是控制流逻辑，不是数据处理）。

这时，LoRA 微调就是唯一解。我们为他们构造了 320 条高质量指令微调数据，每条都包含：

• Instruction ：模拟真实用户模糊提问，如“帮我检查这份财报，有问题就告诉我”；
• Input ：真实的财报 CSV 片段（脱敏）；
• Output ：严格遵循公司规范的 JSON 输出，包括 critical: true 和 halt_on_critical: true 字段。

训练使用 Qwen2-7B，LoRA rank=64，alpha=128，仅用 2 张 A10G（24GB）显存，48 小时完成。上线后，模型在未见过的新财报格式上，首次调用即 100% 遵守中断规则。但代价是：每次 SDK 迭代，都要重新构造数据、重训、回归测试——这正是我们把它列为“第三选项”的原因。

3. RAG 实战：从文档到向量，每一步都是精度战场

3.1 文档预处理：为什么“直接喂 PDF”是自杀行为？

几乎所有失败的 RAG 项目，都死在第一步：文档清洗。我统计过 15 个早期项目，其中 11 个的初始文档源是 PDF。PDF 的本质是“页面布局描述语言”，它把文字、图片、表格、页眉页脚混在一起，而大模型需要的是 语义连贯、结构清晰、无噪声的纯文本段落 。一个典型的 PDF 抽取灾难是：

• 页眉“© 2024 MyLib Docs - Page 15” 被抽成正文开头；
• 表格被转成无意义的空格分隔字符串，如 "Name Age Role Alice 28 Engineer Bob 35 Manager" ；
• 代码块中的缩进被破坏， if condition: 变成 if condition : （冒号前多空格），导致模型误判语法错误。

我们的标准流程是： 拒绝 PDF，拥抱源码即文档（Source-as-Doc） 。这意味着：

• 如果你用 Sphinx，直接解析 .rst 或 .md 源文件；
• 如果你用 TypeDoc（TypeScript），用 typedoc --json 导出结构化 JSON；
• 如果你用 JSDoc（JavaScript），用 jsdoc-api 提取 AST；
• 如果你只有 Markdown README，确保它包含 ## API Reference 和 ### Class: XXX 等标准标题层级。

对于必须处理 PDF 的场景（如老系统遗留手册），我们采用两阶段清洗：

1. Layout-Aware OCR ：用 pymupdf 提取带坐标的文本块，按 Y 坐标聚类为“段落”，过滤掉坐标在页眉/页脚区域（Y < 50 或 Y > page_height - 30）的块；
2. 语义重构 ：用一个轻量级微调过的 distilbert-base-uncased 模型，对每个文本块打标签： [title, heading, paragraph, code, table, footnote] ，然后只保留 heading 和 paragraph ，并将 code 块单独剥离为独立 chunk。

实操心得：我们曾为一个 C++ 库处理 PDF 手册，初始准确率仅 31%。加入 Layout-Aware OCR 后升至 68%，再加入语义标签过滤，最终达 94%。关键不是模型多强，而是 让机器看清“哪里是标题，哪里是正文，哪里是代码” ——这比任何 fancy 向量模型都重要。

3.2 分块策略：代码优先分块法（Code-First Chunking）详解

通用文本分块（如按 500 字符切）在代码文档上效果极差。一段 class DatabaseConnection 的完整定义可能跨 200 行，包含 __init__ , connect() , execute() , close() 四个方法，但通用分块会把它切成 5 个不完整的碎片，模型看到的只是 def connect(self, host: ，根本无法理解。

我们提出的 Code-First Chunking ，核心思想是： 以代码结构为锚点，文档描述为血肉，确保每个 chunk 是一个语义完整的“代码单元” 。具体步骤如下（以 Python 为例）：

1. 语法树解析（AST Parsing） ：用 ast.parse() 加载所有 .py 文件，遍历 ast.ClassDef 和 ast.FunctionDef 节点；
2. 代码块提取 ：对每个 ClassDef ，提取其完整源码（含 docstring 和所有方法）；对每个顶级 FunctionDef ，提取其完整函数体（含装饰器、docstring、函数体）；
3. 文档绑定 ：将 Sphinx .rst 中对应 .. automodule:: mylib.db 的章节内容，按标题匹配，追加到对应 class/function chunk 末尾；
4. 智能截断 ：每个 chunk 总长度上限设为 400 tokens（用 tiktoken 计算），若超限，则优先裁剪 docstring 中的冗长示例，保留核心参数说明和返回值定义。

效果对比：对一个有 12 个类、47 个方法的 SDK，通用分块产生 218 个 chunk，平均长度 280 tokens，但 63% 的 chunk 缺失关键上下文；Code-First Chunking 仅产生 59 个 chunk，平均长度 392 tokens，且 100% 包含完整类定义或函数签名。在 MTEB 检索基准测试中，后者 Recall@5 达 96.2%，前者仅 51.7%。

提示：不要迷信“小 chunk 更好”。我们压测过 chunk_size=100/200/400/800，结论是：对于代码文档，300–500 tokens 是黄金区间。太小则丢失上下文（如看不到 class A 和 class B 的继承关系），太大则降低检索粒度（一个 chunk 包含 5 个不相关函数，模型难以聚焦）。

3.3 向量化与检索：为什么 bge-m3 是当前最优解？

向量模型选型，是 RAG 效果的第二决定性因素。我们横向对比了 7 个主流开源模型（ text-embedding-3-small , bge-large-zh-v1.5 , m3e-base , gte-Qwen2-7B , bge-m3 ），在自建的 500 条“SDK 使用问题”测试集上评估：

模型	MRR@10	检索速度（QPS）	内存占用（GB）	对中文代码术语理解
text-embedding-3-small	0.721	185	0.8	一般（常混淆 async / await ）
bge-large-zh-v1.5	0.832	42	2.1	优秀，但慢
bge-m3（multilingual）	0.897	112	1.3	卓越（专为代码优化）

bge-m3 的胜出，源于其三阶段训练设计：

• Stage 1 ：在 10TB 多语言网页上预训练，建立基础语义；
• Stage 2 ：在 GitHub 上千万级代码-注释对上微调，学习 def xxx(): 和 """This function does...""" 的强关联；
• Stage 3 ：在 Stack Overflow 的“问题-高赞答案”对上强化，特别优化对 how to , why does , error: xxx 等提问模式的响应。

部署时，我们用 sentence-transformers 加载 BAAI/bge-m3 ，设置 normalize_embeddings=True ，并启用 query_instruction_for_retrieval="为这个Python函数查找官方文档：" . 这个 instruction 极其关键——它告诉模型：“你现在不是在做通用语义匹配，而是在做‘代码文档检索’”，能把 MRR@10 再提升 3.2 个百分点。

注意：向量库选型上，我们弃用了 Elasticsearch（配置复杂、向量插件不稳定），也避开了 Pinecone（闭源、成本不可控），最终全线采用 ChromaDB 。它轻量（单机版 50MB）、API 简洁（ collection.add(documents, embeddings, ids) 一行搞定）、且完美支持 bge-m3 的多向量检索（dense + sparse + colbert）。一个 10 万 chunk 的 SDK 文档库，ChromaDB 内存占用仅 1.8GB，QPS 稳定在 95+。

3.4 重排（Rerank）：用 bge-reranker-large 把最后 5% 的精度抠出来

检索（Retrieval）和重排（Rerank）是两个独立阶段。很多团队以为“向量相似度高就一定准”，这是巨大误区。向量模型擅长“找相似”，但不擅长“判真假”。例如，用户问“ load_config() 如何处理 YAML 中的锚点（anchor）？”， bge-m3 可能检索到：

• Chunk A： load_config() 的完整实现，含 yaml.load() 调用，但未提 anchor；
• Chunk B：一篇关于 YAML anchor 的通用教程，未提 load_config() ；
• Chunk C： load_config() 的单元测试，其中一行 # test anchor resolution 。

单纯看向量相似度，A 和 B 可能得分更高；但真正有用的是 C——因为它证明了函数确实支持 anchor。这就是重排的价值。

我们固定使用 BAAI/bge-reranker-large ，它是一个 cross-encoder 模型，能同时看到 query 和 document，进行精细化打分。部署时，我们设置：

• 先用向量检索 Top 50 chunks；
• 再用 bge-reranker-large 对这 50 个做重排，取 Top 3；
• 最后将这 3 个 chunk 拼接为 context，送入大模型。

实测表明，这一步将最终生成代码的准确率（通过单元测试比例）从 73% 提升到 89%。代价是增加约 120ms 延迟，但相比生成错误代码导致的调试时间，这点延迟完全可以接受。

4. Tool Calling 实战：从函数签名到生产就绪的工具链

4.1 Schema 构造：超越 pydantic.schema() 的工业级实践

OpenAPI Schema 是 Tool Calling 的契约，契约不严谨，执行必出错。 pydantic.BaseModel.schema() 生成的 Schema，缺了太多生产环境必需字段。我们自研的 tool-schema-gen 工具，会自动注入以下关键属性：

• x-nullable 扩展字段 ：明确标识哪些字段可为 null ，避免模型生成 "field": null 而函数期望 None ；
• enum 强制枚举 ：对 Literal["a", "b", "c"] ，不仅生成 enum: ["a","b","c"] ，还添加 description: "Valid values are 'a', 'b', or 'c'. Do not use any other value." ；
• format: binary + description ：对 bytes 类型，强制标注 format: binary 和清晰的二进制流说明；
• x-tool-call-id 元字段 ：在每个 tool definition 中加入唯一 ID，便于日志追踪和 A/B 测试。

以一个真实的 image_enhancer.enhance() 函数为例：

def enhance(
    image: bytes,
    method: Literal["sharpen", "denoise", "superres"],
    strength: float = 1.0,
    output_format: Optional[Literal["jpeg", "png"]] = None
) -> bytes:
    """Enhance image quality using specified method."""

tool-schema-gen 生成的 Schema 片段（精简）：

{
  "name": "image_enhancer.enhance",
  "description": "Enhance image quality. Accepts raw image bytes and returns enhanced bytes.",
  "parameters": {
    "type": "object",
    "properties": {
      "image": {
        "type": "string",
        "format": "binary",
        "description": "Raw image bytes (e.g., from open('img.jpg', 'rb').read()). Do NOT pass a file path."
      },
      "method": {
        "type": "string",
        "enum": ["sharpen", "denoise", "superres"],
        "description": "Enhancement method. Valid values are 'sharpen', 'denoise', or 'superres'."
      },
      "strength": {
        "type": "number",
        "minimum": 0.1,
        "maximum": 3.0,
        "default": 1.0,
        "description": "Enhancement strength (0.1 to 3.0). Higher values increase effect but may introduce artifacts."
      },
      "output_format": {
        "type": ["string", "null"],
        "enum": ["jpeg", "png"],
        "x-nullable": true,
        "description": "Output image format. If null, defaults to input format."
      }
    },
    "required": ["image", "method"]
  }
}

实操心得： x-nullable 是我们踩过最痛的坑。某次上线后，用户提问“用默认强度增强”，模型生成了 "strength": null ，而我们的函数参数是 strength: float = 1.0 ，Pydantic 在解析时抛出 ValidationError ，整个调用链崩溃。加上 x-nullable 并在 wrapper 中做 if strength is None: strength = 1.0 ，问题彻底解决。

4.2 Tool Wrapper：安全、可靠、可观测的执行层

Tool Calling 的 Wrapper，不是简单的函数调用，而是一个微型服务网关。我们的标准 Wrapper 包含四层防护：

1. 输入验证层 ：用 Pydantic V2 的 model_validate() 对 JSON 输入做严格校验，失败时返回结构化错误（ {"error": "Invalid 'method': 'blur' is not in ['sharpen','denoise','superres']"} ）；
2. 沙箱执行层 ：对所有函数调用，使用 multiprocessing.Process 启动子进程，设置 timeout=30 和 memory_limit=512MB ，超时或 OOM 则强制 kill；
3. 错误标准化层 ：捕获所有异常（ ValueError , OSError , TimeoutError ），统一转换为 {"error": "Failed to enhance: invalid image format"} 格式；
4. 可观测层 ：记录 tool_call_id , input_hash , execution_time_ms , status （success/error/timeout）到 Loki 日志，并打上 sdk_version 标签。

这个 Wrapper 用 FastAPI 实现，暴露 /tools/{tool_name} 端点。关键代码片段：

@app.post("/tools/{tool_name}")
async def call_tool(tool_name: str, payload: dict):
    try:
        # 1. Input validation
        tool_def = TOOLS_REGISTRY[tool_name]
        validated_input = tool_def.input_model.model_validate(payload)
        
        # 2. Sandboxed execution
        with ProcessPoolExecutor(max_workers=1) as executor:
            future = executor.submit(tool_def.func, **validated_input.model_dump())
            result = await asyncio.wait_for(future, timeout=30)
        
        return {"result": result}
    
    except ValidationError as e:
        return {"error": f"Input validation failed: {str(e)}"}
    except asyncio.TimeoutError:
        return {"error": "Tool execution timed out after 30 seconds"}
    except Exception as e:
        return {"error": f"Tool execution failed: {str(e)}"}

提示：不要在 Wrapper 中做业务逻辑。Wrapper 的唯一职责是“安全地执行函数并返回结果”。所有参数转换、缓存、重试，都应在函数内部或上游服务完成。我们曾因在 Wrapper 中加入 Redis 缓存，导致并发调用时缓存键冲突，返回了错误结果——这是架构性错误。

4.3 大模型侧集成：如何让 GPT-4o “乖乖听话”

模型侧的集成，关键是 System Prompt 的精密设计 和 Tool Calling 的渐进式引导 。

System Prompt 必须包含三要素 ：

• 角色定义 ：“You are an expert Python developer, deeply familiar with the 'mylib' SDK. You only generate code that uses functions from this SDK.”
• 工具约束 ：“You MUST use the provided tools when the user asks for actions (e.g., 'generate', 'validate', 'convert'). Do NOT write custom code for tasks covered by tools.”
• 失败处理 ：“If a tool call fails, you MUST explain the error in plain language and suggest how to fix it (e.g., 'The image format is unsupported. Please use JPEG or PNG').”

渐进式引导 更重要。我们发现，直接让模型“调用工具”，它经常忽略。必须用三步法：

1. 第一步（Query） ：用户问“怎么把 CSV 转成 JSON？”；
2. 第二步（Plan） ：模型回复：“我需要使用 csv_to_json() 工具，请提供 CSV 文件。”；
3. 第三步（Execute） ：用户上传文件，模型调用工具并返回结果。

为此，我们在前端加了一个状态机：当模型返回 tool_calls 时，前端不显示结果，而是自动发起文件上传对话框；上传成功后，再触发第二次调用。这比任何 Prompt Engineering 都有效。

5. LoRA 微调实战：小数据、高回报的精准行为塑造

5.1 数据构造：为什么 300 条比 3000 条更有用？

微调数据的质量，远胜于数量。我们做过对照实验：用同一份 300 条高质量数据（人工编写，覆盖所有边界 case），和一份 3000 条低质量数据（ChatGPT 生成，大量重复和错误），在 Qwen2-7B 上微调。结果：高质量组在 held-out test set 上准确率 89.2%，低质量组仅 63.5%。

高质量数据的构造铁律：

• 100% 来自真实日志 ：从客服系统、Slack 频道、GitHub Discussions 中抓取真实用户提问；
• 100% 由资深工程师撰写回答 ：禁止 AI 生成，确保回答符合公司规范、术语一致、无歧义；
• 100% 覆盖“暗知识” ：如“所有 check_*() 函数必须在发现高危问题时立即返回，不继续检查”、“ export_report() 默认压缩为 ZIP，若指定 format='pdf' 则跳过压缩”。

数据格式严格遵循 instruction-tuning 标准：

{
  "instruction": "用 audit-engine 检查这份财报，只告诉我是否有高危问题。",
  "input": "{'revenue': 1200000, 'expenses': 1500000, 'cash': -300000}",
  "output": "{'status': 'fail', 'critical': true, 'message': 'Cash balance is negative (-300000), indicating severe liquidity risk.', 'halt_on_critical': true}"
}

注意： input 字段必须是 结构化数据 ，而非“请看附件”。模型需要学习从 JSON/YAML/CSV 片段中提取信息，而不是依赖人类解读。

5.2 训练配置：A10G 显存下的极致性价比方案

资源有限是常态。我们的标准配置是 2×A10G（24GB），目标是 48 小时内完成训练。关键配置如下：

• Base Model ：Qwen2-7B（15B 参数，但 7B 版本在 A10G 上可训）；
• LoRA Rank ：64（rank=32 精度掉 5%，rank=128 显存溢出）；
• Alpha ：128（alpha/rank=2，经验值）；
• Target Modules ： q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj （覆盖所有注意力和 FFN 层）；
• Batch Size ：per_device_train_batch_size=1，gradient_accumulation_steps=8（等效 batch=16）；
• Optimizer ： paged_adamw_32bit （节省显存）；
• LR Scheduler ：cosine，warmup_ratio=0.03。

训练命令（使用 peft + transformers ）：

python src/train_lora.py \
  --model_name_or_path Qwen/Qwen2-7B \
  --dataset_path data/audit_tune.json \
  --output_dir ./lora_output \
  --lora_rank 64 \
  --lora_alpha 128 \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 8 \
  --learning_rate 2e-4 \
  --num_train_epochs 3 \
  --save_steps 100 \
  --logging_steps 10 \
  --fp16 True \
  --report_to none

实测：3 个 epoch，总 step=1200，耗时 44 小时，最终 loss 从 2.1 降到 0.38。最重要的是，**在未参与训练的 50 条 holdout 数据上，F1-score 达