AI 应用后端工程化：从原型到可交付系统 · 第 08 篇 · 第二章 · 知识与工具
解析接口规范、选择操作、补齐认证并生成工具定义，说明 Schema 如何连接模型意图与 HTTP API。
OpenAPI 常被当作接口文档的数据源：浏览器渲染一张漂亮页面，开发者照着调用。它更深一层的价值是机器可读。只要规范足够准确，系统就能从中生成参数验证、客户端代码，甚至把一个 HTTP 操作转换成模型可以选择的工具。
转换并不是把整份 JSON 交给模型。真正工作包括选择操作、解析引用、合并参数、处理认证、限制目标地址，并把 HTTP 世界的失败翻译成稳定工具结果。
两种协议之间的翻译
flowchart LR
Spec[OpenAPI 文档] --> Select[选择 operation]
Select --> Resolve[解析引用与参数]
Resolve --> ToolSchema[工具 Schema]
ToolSchema --> Model[模型选择]
Model --> Validate[参数校验]
Validate --> Request[构造 HTTP 请求]
Auth[认证配置] --> Request
Request --> Normalize[响应归一化]
Normalize --> Result[工具结果]
OpenAPI 的 operationId 可以成为工具名，summary 与 description 可以帮助模型判断用途，path、query、header 和 request body 则要合并成清晰参数。这里需要保留来源位置，因为同名参数出现在不同位置时，HTTP 构造方式完全不同。
先缩小规范，再交给模型
一份企业 OpenAPI 可能包含几百个操作。全部转换不仅浪费上下文，还会暴露模型不该调用的管理接口。导入阶段应允许选择白名单，运行时再根据用户权限和任务场景筛选可见工具。
{
"operationId": "orders_get",
"method": "GET",
"path": "/orders/{order_id}",
"parameters": {
"order_id": {"type": "string", "required": true}
},
"allowed_status": [200, 404]
}
模型需要的是清晰、较小的调用契约，而执行器还需要 method、path、认证和响应限制。可以用两个实体分别表示“模型可见工具”和“内部执行计划”，避免把服务器地址与敏感 Header 暴露进 Prompt。
$ref 与组合类型不能靠字符串拼接
OpenAPI Schema 支持 $ref、allOf、数组、枚举、可空类型和嵌套对象。手工遍历几个字段很快会漏掉边界。应使用成熟解析器把引用展开或保留可解析图，再转换为目标工具协议支持的子集。
遇到目标模型不支持的 Schema 特性，需要明确降级。例如 oneOf 可以转成带判别字段的对象，无法可靠表达时则拒绝导入，而不是静默删除验证条件。规范验证越早，运行时越少出现模型“参数看起来正确但 HTTP 拒绝”的情况。
认证不属于模型参数
绝不能让模型填写真实 API Key。模型只提供业务参数，执行器根据当前用户、Provider 和环境注入凭证。即使 OpenAPI 把 Header 参数写在普通 parameters 中，导入器也应识别安全方案并从模型 Schema 排除。
多租户环境中，同一个工具定义可能对应不同用户凭证。管理面保存加密后的凭证引用，执行面在授权后临时解密使用，日志只记录凭证 ID。这样既能复用工具，又不会把密钥做成全局配置。
HTTP 能访问哪里
自定义 API 工具天然带来 SSRF 风险。若用户可以导入任意 server URL，模型可能被诱导访问 127.0.0.1、云元数据地址或内网管理端点。仅靠 URL 格式校验不够，还要解析 DNS、限制协议和端口、阻止私有网段，并防止重定向绕过。
生产系统常采用显式域名白名单或受控网络代理。执行器设置连接与读取超时、最大响应体和允许内容类型。返回 HTML 或几百兆文件时，不应原样放进模型上下文。
响应需要重新成为一个契约
HTTP 的 200 不一定代表业务成功，404 也可能是模型可以处理的正常结果。转换器应根据状态码、内容类型和响应 Schema，产生统一的成功或错误结构。对于超长 JSON，可以选取配置字段或生成摘要，同时保留原始响应引用供人工查看。
一个坏实现会把 requests.request(**model_arguments) 当作全部工作。模型便可能控制 method、完整 URL 和 headers，响应也未经限制。这相当于向模型提供一个通用内网浏览器，风险远高于普通查询工具。
从 OpenAPI 推广到其他连接器
数据库元数据可以生成只读查询工具，GraphQL introspection 可以生成候选操作，消息队列 Schema 可以生成事件发布表单。共同方法是：解析机器规范，选择安全子集，生成模型契约，由确定性执行器掌控真实连接。
练习可以选一个公开的天气 API，只导入查询当前天气的 operation。验证缺少必填参数、枚举越界、404、超时和超长响应五种情况。最后检查模型看到的 Schema 中没有服务器密钥，也不能修改目标域名。
四次提交展现的转换过程
67f4ec4：建立 API 工具模型、服务和路由，先定义管理对象。07f9091：加入 OpenAPI 规范验证，把错误挡在导入阶段。89e7847：实现自定义 API 工具创建，规范开始生成可管理能力。a184074：补充 Provider 信息查询，让配置与运行状态可以被检查。
顺序再次说明：先建领域模型，再验证输入，再创建资源，最后补查询接口。面对任何“从规范自动生成能力”的功能，这个顺序都比直接拼请求更稳。