1. 从手写工具函数到自动生成一个真实的需求场景手里维护着几十个微服务每个服务都有一套 REST API加起来少说五十个接口。每次想让大模型帮我调这些接口就得手动写一遍工具描述——接口名、参数、类型、说明一个都不能少。写十个还能忍写到第三十个的时候我开始怀疑人生。这不是我一个人的痛点。团队里做 AI 应用开发的同事几乎都卡在同一个地方REST API 和 LLM 工具调用之间的那道手工翻译墙。接口文档是给人和传统客户端看的大模型需要的是结构化的工具定义两者之间的鸿沟全靠人肉填。后来我换了个思路既然 OpenAPI 规范已经把接口描述得清清楚楚为什么不让程序自动把它转成 DeepSeek 能用的工具定义五十个接口一份 OpenAPI 文档跑一遍脚本工具列表全出来了。改接口的时候重新生成一次永远和文档保持同步。这套方案解决的核心问题就一个消除 REST API 到 LLM 工具之间的手工转换成本。适合谁参考任何在给大模型接外部接口的开发者尤其是接口数量多、变更频繁的场景。Python 基础不用太深能看懂字典和列表就行。2. 整体设计思路为什么选 OpenAPI 作为中间层2.1 手工写工具定义的三个致命问题先说说为什么手写工具定义这条路走不通。我踩过的坑大概归为三类。第一类是同步问题。接口改了参数工具定义忘了改模型调用时传了个已经不存在的字段报错信息还特别隐晦。这种问题在接口数量少的时候靠人盯还能应付超过二十个接口漏改几乎是必然的。第二类是一致性问题。同一个参数在 A 接口的工具定义里叫user_id在 B 接口里手滑写成了userId。模型看到两套命名调用时容易混淆。手工维护的东西一致性全靠自觉而自觉在赶工期的时候最不可靠。第三类是描述质量问题。工具定义里的 description 字段写得好模型调用准确率就高写得敷衍模型就瞎猜。手写的时候写到后面几个接口描述往往就变成“获取数据”这种废话模型根本不知道这个工具到底干什么。2.2 OpenAPI 天然就是工具定义的原材料OpenAPI 规范里已经包含了生成工具定义所需的全部信息路径、方法、参数名、参数类型、是否必填、参数说明、请求体结构。这些信息本来就是给客户端生成器用的而 LLM 的工具定义本质上也是一种客户端描述。我选择 OpenAPI 作为中间层核心理由有三条。信息完整度最高。相比 Postman 集合或者手写的接口清单OpenAPI 的结构化程度最好参数的类型和约束都有明确表达。DeepSeek 的工具调用需要 JSON Schema 来描述参数而 OpenAPI 的参数定义和 JSON Schema 之间几乎是一一对应的。生态成熟。Python 里解析 OpenAPI 的库很成熟prance、openapi-spec-validator这些工具能帮你处理引用解析和格式校验。不用自己造轮子去解析 YAML 里的$ref省了大量边界情况的处理。变更可追踪。OpenAPI 文档通常跟着代码走接口改了文档也会更新。以文档为源头生成工具定义等于把工具定义挂在了接口变更的流水线上天然具备同步能力。2.3 整体架构三层转换整个方案的架构可以拆成三层。第一层是解析层负责读取 OpenAPI 文档把 YAML 或 JSON 解析成 Python 字典处理掉所有的$ref引用输出一份扁平化的接口清单。第二层是转换层把每个接口的路径、方法、参数、请求体映射成 DeepSeek 工具调用所需的 JSON Schema 格式。这一层是核心需要处理类型映射、必填判断、描述提取等逻辑。第三层是输出层把转换后的工具定义组装成 DeepSeek API 要求的格式可以直接传给tools参数使用。三层之间职责清晰解析层和输出层相对固定转换层是定制化最多的地方不同项目的接口风格不一样需要根据实际情况调整。3. 核心细节解析OpenAPI 到 DeepSeek 工具的映射规则3.1 工具名称的生成策略DeepSeek 对工具名称有格式要求只能用字母、数字、下划线和短横线长度也有限制。OpenAPI 里的路径和方法组合需要转换成合法的工具名。我的做法是用方法_路径的组合把路径里的斜杠替换成下划线路径参数的花括号去掉。比如GET /users/{user_id}/orders转换成get_users_user_id_orders。这里有个细节要注意路径参数在工具名里保留原名不要做缩写。我试过把user_id缩成uid结果模型调用时经常把参数名和工具名里的片段搞混。保持原名虽然工具名长一点但模型理解起来更准确。如果工具名超过长度限制我的处理是保留方法前缀和路径的最后两段前面的部分截断。比如get_api_v2_internal_users_user_id_orders太长就变成get_users_user_id_orders。截断的时候要保证唯一性如果截断后重名就在后面加数字后缀。3.2 参数类型的映射表OpenAPI 的参数类型和 JSON Schema 的类型不是完全一一对应需要一张映射表来处理。下面是我实际使用的映射规则。OpenAPI 类型JSON Schema 类型备注stringstring直接映射integerinteger直接映射numbernumber直接映射booleanboolean直接映射arrayarray需要处理 items 子类型objectobject需要处理 propertiesstring format: datestring加 description 说明格式string format: date-timestring加 description 说明格式string enumstring把 enum 值放进 description对于array类型items 的类型也要递归映射。如果 items 是对象就把对象的 properties 也展开。这一步容易出问题的地方是嵌套层级太深我的建议是嵌套超过三层的对象在 description 里说明结构不要完全展开否则工具定义会变得非常臃肿模型反而抓不住重点。3.3 必填参数的判断逻辑OpenAPI 里判断参数是否必填要看两个地方。路径参数默认必填查询参数和请求体参数看required字段。路径参数不用看required因为路径里出现了就一定是必填的。查询参数和 header 参数检查required: true。请求体参数检查 requestBody 的required字段以及 body schema 里各个属性的required数组。这里有个坑有些 OpenAPI 文档写得不够规范路径参数没有标required: true但实际调用时缺了就会 404。我的处理是路径参数一律视为必填不管文档里怎么标。这个规则在实际使用中没出过问题。3.4 描述信息的提取与增强工具定义里的 description 字段直接决定模型能不能正确选择工具。OpenAPI 里的summary和description是主要来源但很多时候这两个字段写得很简略。我的增强策略是如果description长度超过二十个字符直接用如果太短或者为空就用summary加上参数说明拼一段。拼的时候格式是“功能描述。参数参数名类型参数名类型”。这样模型至少知道这个工具需要什么参数。还有一个技巧在 description 末尾加上“调用此工具时请确保参数完整”这类提示能降低模型漏传参数的概率。我实测下来加了这句话之后参数缺失的报错减少了大概三成。4. 实操过程从零生成五十个工具定义4.1 环境准备与依赖安装先把环境搭起来。Python 版本建议 3.8 以上我用的是 3.10。需要安装的库不多核心是pyyaml用来解析 YAML 格式的 OpenAPI 文档requests用来在需要时拉取远程文档。pip install pyyaml requests如果 OpenAPI 文档里有复杂的$ref引用建议加上prance库它能自动处理引用解析。pip install prance我个人的习惯是先用prance解析一遍把引用都展开输出一份扁平的字典后续处理就不用操心$ref了。虽然多一步但省去了大量边界情况的判断。4.2 解析 OpenAPI 文档假设手里有一份api-spec.yaml先把它读进来。下面是我用的解析函数核心是把 paths 里的每个路径和方法组合提取出来。import yaml def load_spec(path): with open(path, r, encodingutf-8) as f: spec yaml.safe_load(f) return spec def extract_operations(spec): operations [] paths spec.get(paths, {}) for path, path_item in paths.items(): for method in [get, post, put, delete, patch]: if method in path_item: op path_item[method] operations.append({ path: path, method: method, operation: op }) return operations这段代码跑完operations列表里就是所有接口。五十个接口的话这个列表长度就是五十。如果文档里有$ref引用没展开op里可能拿不到完整的参数信息所以前面建议用prance先处理一遍。4.3 转换单个接口为工具定义这是核心的转换函数。输入是一个 operation 字典输出是 DeepSeek 工具定义的字典。def convert_to_tool(op_info): path op_info[path] method op_info[method] op op_info[operation] tool_name generate_tool_name(method, path) description build_description(op) parameters build_parameters(op, path) return { type: function, function: { name: tool_name, description: description, parameters: parameters } }generate_tool_name按前面说的规则生成名称。build_description提取 summary 和 description 并做增强。build_parameters是最复杂的部分需要把路径参数、查询参数、请求体参数合并成一个 JSON Schema。4.4 参数合并的详细逻辑参数合并要处理三种来源路径参数、查询参数、请求体。我的做法是先把路径参数和查询参数合并到 properties 里再把请求体的 properties 合并进来。def build_parameters(op, path): properties {} required [] # 处理路径参数和查询参数 for param in op.get(parameters, []): name param[name] schema param.get(schema, {}) properties[name] convert_schema(schema, param.get(description, )) if param.get(in) path or param.get(required): required.append(name) # 处理请求体 request_body op.get(requestBody, {}) if request_body: content request_body.get(content, {}) json_content content.get(application/json, {}) body_schema json_content.get(schema, {}) if body_schema: body_props body_schema.get(properties, {}) for prop_name, prop_schema in body_props.items(): properties[prop_name] convert_schema(prop_schema, prop_schema.get(description, )) required.extend(body_schema.get(required, [])) return { type: object, properties: properties, required: list(set(required)) }convert_schema负责把 OpenAPI 的 schema 转成 JSON Schema 格式处理类型映射和 enum 值。这里要注意required去重因为路径参数和请求体可能有重叠。4.5 批量生成与输出把上面的函数串起来批量处理所有接口。def generate_all_tools(spec_path): spec load_spec(spec_path) operations extract_operations(spec) tools [] for op_info in operations: tool convert_to_tool(op_info) tools.append(tool) return tools tools generate_all_tools(api-spec.yaml) print(f生成了 {len(tools)} 个工具定义)五十个接口跑下来大概一两秒就完成了。输出的tools列表可以直接传给 DeepSeek 的 API。4.6 接入 DeepSeek 调用生成工具定义之后调用 DeepSeek 的时候把 tools 传进去。import requests def call_deepseek(messages, tools): response requests.post( https://api.deepseek.com/chat/completions, headers{ Authorization: Bearer YOUR_API_KEY, Content-Type: application/json }, json{ model: deepseek-chat, messages: messages, tools: tools, tool_choice: auto } ) return response.json()这里有个实际经验工具数量多的时候tool_choice建议用auto让模型自己判断是否需要调用工具。如果强制用required模型每轮都会调工具即使问题根本不需要调接口反而浪费 token。5. 常见问题与排查技巧实录5.1 工具定义生成后模型不调用这是最常见的问题。生成了一堆工具模型却一个都不用直接用自己的知识回答。排查思路按下面顺序来。先检查工具数量。DeepSeek 对单次请求的工具数量有上限超过上限的工具会被忽略。五十个工具如果一次全传可能超出限制。我的做法是按业务域分组每次只传相关的工具。比如用户相关的接口传用户工具订单相关的传订单工具。再检查 description 质量。如果 description 写得太泛模型判断不出这个工具和当前问题的关联。把 description 改得更具体包含“用于查询”“用于创建”这类动作词能明显提升调用率。最后检查参数 schema。如果 schema 里有模型不认识的类型或者格式错误模型可能直接跳过这个工具。用 JSON Schema 校验工具跑一遍确保格式合法。5.2 参数传递错误模型调用了工具但参数传错了。常见的有三种情况。第一种是参数名不匹配。模型传了userId但 schema 里定义的是user_id。这是命名风格不一致导致的。解决办法是在 description 里明确写出参数名或者在 schema 的 property 描述里强调“参数名必须为 user_id”。第二种是类型错误。schema 里定义的是 integer模型传了字符串123。这种情况在 DeepSeek 上比较少见但如果出现可以在 description 里注明“此参数为数字类型”。第三种是漏传必填参数。前面提到的在 description 末尾加提示能缓解这个问题。另外可以把必填参数在 description 里单独列出来格式是“必填参数xxx, yyy”。5.3 接口变更后工具定义不同步这是流程问题不是技术问题。我的做法是把生成脚本挂到 CI 里每次 OpenAPI 文档更新自动重新生成工具定义并部署。这样工具定义永远和文档一致。如果 CI 不方便接至少要在文档变更时手动跑一次生成脚本。我试过忘记跑结果模型调用了一个已经删除的接口报错信息找了半天才定位到是工具定义过期。5.4 常见问题速查表问题现象可能原因排查方法解决措施模型不调用工具工具数量超限检查 tools 列表长度按业务域分组传递模型不调用工具description 太泛查看生成的 description增加动作词和具体说明参数名不匹配命名风格不一致对比 schema 和实际传参description 里强调参数名漏传必填参数模型忽略 required检查 required 数组description 末尾加提示工具定义过期文档更新未重新生成对比文档和工具定义接入 CI 自动生成类型错误schema 类型不明确检查 convert_schema 输出description 注明类型5.5 几个踩过的坑第一个坑是$ref没展开。OpenAPI 文档里参数用$ref引用公共组件解析的时候如果没展开拿到的就是个引用字符串不是实际 schema。用prance解析能自动展开或者自己写递归函数处理。第二个坑是 enum 值丢失。OpenAPI 里参数有 enum 约束转换的时候如果只取 type 不取 enum模型就不知道可选值有哪些。我的处理是把 enum 值拼进 description格式是“可选值a, b, c”。第三个坑是路径参数的花括号。生成工具名的时候要去掉花括号但生成参数名的时候要保留原名。我一开始把花括号也带进了参数名结果模型传参时带了花括号接口直接 404。6. 进阶优化让工具定义更懂模型6.1 按业务域分组减少工具数量五十个工具一次全传模型的选择压力很大。我的优化是按业务域分组比如用户域、订单域、商品域每组十到十五个工具。调用的时候根据用户问题判断属于哪个域只传对应域的工具。判断域的方法可以用关键词匹配也可以用一个小模型做分类。我用的是关键词匹配维护一个域到关键词的映射表命中哪个域就传哪组工具。简单但有效实测调用准确率提升明显。6.2 工具描述的模板化增强为了让 description 质量稳定我设计了一个模板。格式是“【动作】【对象】【补充说明】【参数提示】”。动作词从接口方法推导GET 对应“查询”POST 对应“创建”PUT 对应“更新”DELETE 对应“删除”。对象从路径和 summary 提取。补充说明用原 description。参数提示自动生成。模板化之后即使原文档的 description 写得很差生成的工具描述也能保持在一个可用的水平线上。6.3 缓存与增量更新五十个接口每次全量生成虽然快但如果接口数量涨到几百个全量生成就不划算了。我的做法是给每个接口算一个哈希基于路径、方法、参数、描述内容。哈希没变的接口工具定义直接复用缓存只重新生成哈希变化的接口。这样接口变更时只有受影响的工具定义会重新生成其他的保持不变。对于模型来说工具定义的稳定性也有好处不会因为无关接口的变更导致工具列表整体变化。6.4 工具调用的结果回传处理工具定义生成只是第一步模型调用工具之后接口返回的结果要回传给模型。这部分逻辑在调用侧处理但和工具定义的设计有关。我的经验是接口返回结果要做裁剪。REST API 返回的 JSON 往往包含大量模型不需要的字段比如时间戳、内部 ID、分页信息。直接全量回传会占用大量 token还可能干扰模型判断。我的做法是在工具定义里加一个response_filter字段标注哪些字段需要保留调用侧根据这个字段裁剪结果。这个字段不是 DeepSeek 标准要求的但放在工具定义的扩展字段里不影响调用调用侧读取后做处理即可。7. 实际效果与个人体会这套方案在我们团队落地之后最直接的变化是接口对接的时间从原来的按天算变成了按分钟算。新接口上线OpenAPI 文档更新跑一遍脚本工具定义就绪。以前需要一个人专门维护工具定义现在这个人力省下来了。模型调用接口的准确率从手工写工具定义时的七成左右提升到了九成以上。提升主要来自两个方面一是描述质量稳定了模板化生成不会出现敷衍的描述二是参数定义和接口文档严格一致不会出现参数名对不上的情况。我个人在实际操作中的体会是这套方案的价值不在于技术有多复杂而在于把一件重复的手工劳动变成了自动化的流程。OpenAPI 文档本来就是接口的单一事实来源以它为源头生成工具定义逻辑上最顺维护成本最低。最后分享一个小技巧生成工具定义之后别急着全量上线。先拿十个接口跑一轮观察模型的调用情况根据实际表现调整 description 的模板和参数提示的措辞。调优一轮之后再全量铺开能避免很多返工。工具定义的质量最终还是要靠实际调用数据来验证生成只是起点。