> 研究对象：Song et al., *RestGPT: Connecting Large Language Models with Real-World RESTful APIs*, arXiv:2306.06624v2（北京大学）
> 配套代码：`RestGPT-main/`
> 研究焦点：OpenAPI Specification（OAS，又名 Swagger）在这套“LLM + 真实 RESTful API”框架里扮演什么角色、创造了什么价值。
>
> **研究路径**：本文采取「代码先行、论文印证」的剖析顺序——先逐文件拆解 `RestGPT-main/` 中 OAS 是如何被“消费”的（第 1 节），再回到论文的动机与形式化论述（第 2、3 节），最后用实验与局限收束。这样安排是因为：OAS 在 RestGPT 里不是抽象概念，而是一份份 `.json` 文件与一段段被抽取、被蒸馏、被喂给提示词的字段，只有先把代码看透，论文的“三重角色”才立得住。
>
> - 论文地址：https://arxiv.org/abs/2306.06624
> - 代码仓库：https://github.com/Yifan-Song793/RestGPT

---

## 3. OAS 在 RestGPT 架构中的三重角色（核心）

论文第 3.1 节明确指出：**“we designate different modules to read distinct parts of the OpenAPI Specification (OAS)”**，通过信息分流在有限上下文里最大化利用 OAS。这一论断在第 1 节的代码剖析中已逐项得到印证：

```
 OpenAPI Specification (OAS)
 ┌──────────────┼──────────────┐
 │ │ │
 ①端点描述(全部) ②详细文档(单个) ③响应 Schema(单个)
 │ │ │
 API Selector Caller Parser
 (选哪个 API) (填参/请求体) (生成 Python 解析代码)
```

> 论文图 1：RestGPT 整体架构。Planner、API Selector、Executor（Caller + Parser）组成由粗到细的在线规划框架；底部虚线框中的 OpenAPI Specification 被拆成 API Desc. / API Doc. / Response Schema 分别喂给三个模块。

![fig1_architecture.png](https://developer.qcloudimg.com/http-save/yehe-11563618/e4abc1a986b33bb77fa61dbe72b10db7.png)


### 角色 ①：API Selector —— 消费「全部端点的描述」，做粗粒度选择

- 输入：所有 API 的 `METHOD path + description` 列表（`api_selector.py:118` 中 `api_name_desc`）。
- 作用：在“接口全貌”中为每个自然语言子任务挑出合适的 API 调用计划。
- 论文原话：“the API selector reads the endpoint descriptions of all APIs to select a proper API for solving the current sub-task.”

### 角色 ②：Caller —— 消费「所选 API 的详细文档」，做细粒度执行

- 输入：当前 API plan 命中的那个端点的完整 docs（`caller.py:251-269`），包含 parameters / requestBody / 200 响应结构，转成 YAML 后**截断到 1500 token** 塞进 Caller 提示词。
- 作用：让 LLM 依据文档组织正确的参数（params）或请求体（data）。**注意**：Caller 并不直接生成可执行的 REST 代码，而是产出声明式 JSON 交给 `requests_wrapper` 执行——代码细节见第 1.5 节。
- 论文原话：“the caller uses the detailed documents of the API within the API plan to generate the correct API calling parameters and request body.”

### 角色 ③：Parser —— 消费「响应 Schema」，做程序化信息提取（PAL）

- 输入：该端点的 `responses.content.application/json.schema.properties`（`parser.py:208-211`），截断到 2500 token，作为 `CODE_PARSING_SCHEMA_TEMPLATE` 的 `response_schema` 字段。
- 机制：让 LLM 基于 **schema + 自然语言查询** 生成 Python 代码，用 `PythonREPL` 在 `data`（真实响应 JSON）上执行抽取（Program-Aided Language Models）。完整代码与三级回退见第 1.6 节。
- 三级回退（`parser.py:_call`）：
 1. 仅用 **schema** 生成代码执行；
 2. 代码失败 → 用 **schema + 真实 JSON 片段** 再生成代码；
 3. 仍失败 → 直接让 LLM 读 JSON 抽取（兜底）。
- 论文原话（3.3）：“we make use of the response schema defined in the OAS. Specifically, we utilize the coding capability of LLM to generate Python parsing code based on the provided schema... If there are no execution exceptions or errors, the output is returned. Otherwise, the LLM is prompted to parse the response directly as a backup.”

> 关键洞察：OAS 的三个字段分别服务“选 / 填 / 取”三个阶段，且按上下文预算**分级节流**（全量描述 vs 单接口文档 vs 截断的 schema），这是它能塞进 LLM 有限窗口的工程核心——而第 1 节展示的 `oas_utils.py` 蒸馏层正是这一节流策略的代码化身。

---

## 4. OAS 创造的价值（实验证据）

### 4.1 可扩展性 / 即插即用（plug-and-play）

- Table 1 中 RestGPT 在 Schema 列标 `RESTful`、Extensibility 列标 `++`、支持 `100+` API；而此前方法多为 `Specialized` 工具，且 Gorilla 之外大多无检索式可扩展。

![table1_comparison.png](https://developer.qcloudimg.com/http-save/yehe-11563618/51349d0297907801095eb796d9d7454b.png)

- 论文结论（2.1）：“While AutoGPT relies on developers to ensure compatibility with various applications, RestGPT can be integrated with any RESTful API-based applications in a plug-and-play fashion.” —— 这一能力的**前提正是 OAS 提供了统一接口描述**。
- 代码层面印证：换场景只需换 `specs/*.json` + 在 `run.py` 里改几行（`reduce_openapi_spec(..., merge_allof=...)`），无需改模型逻辑（见第 1.1 节两份 spec 文件）。

### 4.2 消融实验：去掉 Schema-based Parser 性能暴跌

Table 4（w/o Parser）：用“直接 LLM 读 JSON”替换“基于 OAS schema 的代码生成解析器”：

| 场景 | RestGPT (Success%) | w/o Parser (Success%) | RestGPT (CP%) | w/o Parser (CP%) |
| --- | --- | --- | --- | --- |
| TMDB | **75.0** | 46.0 | **79.0** | 53.0 |
| Spotify | **72.7** | 47.3 | **74.5** | 52.7 |

![table4_success.png](https://developer.qcloudimg.com/http-save/yehe-11563618/59e566e3ebcfb279d0a3ad4145b3cede.png)

> 论文解读：“the schema-based parser enables LLMs to better comprehend and parse the real-world API responses with complicated structure.” —— 这直接证明了 **OAS 响应 schema 是解析质量的关键贡献者**（代码机制见第 1.6 节）。

### 4.3 噪声 API 扩展曲线（5.4 Scaling Curves）

论文在 TMDB 上从 10 个 API 逐步加入“噪声 API”。结果（图 4c）：所有基线随噪声 API 增多而退化，而 RestGPT **几乎不受影响**。论文归因于“strong extensibility”——本质来自 OAS 让 API 选择可在标准化描述空间里稳定检索。

### 4.4 案例：694 行 JSON 的解析（附录 C / 图 8）

对比实验显示 RESTful API 响应常为冗长复杂 JSON（案例 JSON 达 **694 行**）。RestGPT Parser 基于 OAS 响应 schema 生成抽取代码（如 `movies_directed = [m['title'] for m in data['crew'] if m['job']=='Director']`，见第 1.6 节），避免了让 LLM 直接读 694 行 JSON，显著提升效率与准确率。

![fig8_parser_case.png](https://developer.qcloudimg.com/http-save/yehe-11563618/2d9eb520b8a8677d15b7bc599db8dd77.png)

---

## 5. OAS 的局限与失败模式

论文与代码共同揭示，OAS 虽核心，但并非银弹：

1. **依赖 LLM 正确“消费”OAS**：错误分析（5.3）显示多数错误发生在 Planner / API Selector——API Selector 会**幻觉出 OAS 中不存在的路径参数**（如编造 `tv_id`）。OAS 提供了事实，但 LLM 仍可能偏离。
2. **OAS 自身需预处理**：`$ref` 嵌套、`allOf` 合并、字段截断（1500/2500 token）说明原始 OAS 不能直接喂给 LLM，需要 `oas_utils.py` 这类“蒸馏层”（见第 1.2、1.3 节）。
3. **Schema 截断可能丢信息**：为省 token 对 schema 截断（`parser.py:215` 的 `max_schema_length=2500`），极端情况下可能裁掉需要的字段。
4. **小模型不可行**：Table 4 显示 Llama2-13B 完全无法遵循提示（Success 0%），Vicuna-13B 仅 9%，说明 OAS 驱动范式**强依赖强基座 LLM**（text-davinci-003 / ChatGPT）。

---

## 6. 结论与启示

1. **OAS = 通用语义接口契约**。它把“千千万万个异构真实 API”统一成 LLM 可理解的标准化文本，是 RestGPT 能“连真实世界而非玩具工具”的根本前提。
2. **字段级分发是关键工程技巧**。将 OAS 的「端点描述 / 详细文档 / 响应 schema」分别路由给 Selector / Caller / Parser，并用截断与 `$ref` 解析控制 token 预算，解决了“API 多 + 上下文小”的矛盾。
3. **响应 schema 带来可量化的解析增益**（w/o Parser 消融 +30% success），且支持 Program-Aided（代码执行）这一更鲁棒的解析范式。
4. **仍受限于 LLM 本身**：OAS 提供“正确信息”，但是否“用对信息”取决于模型能力；这指向未来方向——更强的规划模型、对 OAS 的检索增强、以及更完善的 schema 校验/补全。

> 对后续研究的提示：若想复现或超越 RestGPT，第一步往往不是改模型，而是**拿到一份高质量、解引用彻底的 OAS**，并设计好“OAS → 各模块提示词”的字段映射与截断策略——这正是本仓库 `specs/` + `oas_utils.py` 已经示范好的范式（第 1 节已逐一拆解）。

---

## 附：论文 ↔ 代码 对照速查

| 论文论述 | 代码落点 |
| --- | --- |
| RESTful 遵循 OAS，可即插即用（2.2 / Intro） | `run.py:36-55` 加载 `specs/*_oas.json` |
| 模块各取 OAS 不同部分（3.1） | `api_selector.py:118` `caller.py:251-269` `parser.py:208-211` |
| 用响应 schema 生成解析代码（3.3） | `parser.py`: `CODE_PARSING_SCHEMA_TEMPLATE` + `PythonREPL` |
| OAS 蒸馏以控上下文（3.1/3.3） | `oas_utils.py` : `reduce_openapi_spec` |
| 计划须命中 OAS 白名单 | `utils.py` : `get_matched_endpoint` + `api_selector.py:188` |
| 提示词受 LangChain OpenAPI agent 启发 | `utils.py:8` 导入 `ReducedOpenAPISpec` |
| 消融：去掉 schema parser 退化为直读 JSON | `parser.py` : `SimpleResponseParser` |

研究对象：Song et al., RestGPT: Connecting Large Language Models with Real-World RESTful APIs, arXiv:2306.06624v2（北京大学） 配套代码：RestGPT-main/ 研究焦点：OpenAPI Specification（OAS，又名 Swagger）在这套“LLM + 真实 RESTful API”框架里扮演什么角色、创造了什么价值。

论文研究：OpenAPI 规范作为 LLM 操控应用的语义接口【下】

在 RestGPT 中，OAS 不是可有可无的“文档”，而是整个系统连接 LLM 与任意真实 API 的「通用语义接口契约」

人工智能

后端

开发工具

RestGPT研究通过OpenAPI规范(OAS)实现LLM与真实RESTful API的连接，OAS在系统中扮演三重角色：API选择器使用端点描述进行粗选，调用器利用详细文档生成参数，解析器基于响应Schema生成Python代码提取数据。实验证明OAS显著提升API扩展性和解析效率，但依赖LLM正确理解规范内容。

代码解释

RESTful API

ChatGPT

路由

Python

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

论文研究：OpenAPI 规范作为 LLM 操控应用的语义接口【下】-腾讯云开发者社区-腾讯云

论文研究：OpenAPI 规范作为 LLM 操控应用的语义接口【下】

论文研究：OpenAPI 规范作为 LLM 操控应用的语义接口【下】

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐