当前位置：首页 > news >正文

[RestGPT] OpenAPI规范(OAS)

news 2025/8/23 17:56:58

链接：https://openapi.apifox.cn/

第2章：OpenAPI规范(OAS)

欢迎回来🐻‍❄️

在第1章：配置与环境中，我们学习了如何设置RestGPT的"飞行检查清单"——为它提供连接TMDB或Spotify等在线服务所需的密钥和设置。

现在RestGPT已经知道如何连接，接下来的关键问题是：

它实际能用这些服务做什么，以及它应该如何提出请求？

这就是**OpenAPI规范(OAS)**的用武之地~

核心理念

想象你有一台新的智能设备，比如一台高级咖啡机。

它已经接通电源（你的环境变量！），但你如何让它制作一杯拿铁？你需要一本使用说明书！这本说明书会告诉你：

有哪些功能按钮（如"煮咖啡"、“蒸汽牛奶”）
每个功能需要什么原料（如"咖啡豆"、“牛奶量”）
你会得到什么样的饮品（如"一杯浓缩咖啡"）

在在线服务领域，**OpenAPI规范(OAS)就是这样的详细说明书，不过是针对应用程序接口(API)**的。

它是一种标准化的方式来描述在线服务的功能。

对RestGPT而言，这至关重要，因为它帮助我们的智能助手理解并与众多不同应用程序交互，而无需为每个应用程序重新编程。

RestGPT中OAS的关键概念

完整的OAS可能相当复杂，但对RestGPT而言，我们关注的是这个"说明书"的简化版本。以下是RestGPT关心的关键部分：

操作(或端点)：
- 定义：这些就像是说明书中的特定"按钮"或"食谱"。每个操作描述一个可执行的动作，例如：
  - “获取特定电影的详细信息”
  - “搜索人物”
  - “向Spotify播放列表添加歌曲”
- RestGPT如何使用：RestGPT需要知道有哪些可能的操作。当你要求RestGPT"找到电影《春光乍泄》的导演"时，它会查阅说明书寻找能获取电影演职员表或人物详细信息的操作。
输入(参数)：
- 定义：对于每个操作，说明书列出了所需的"原料"或信息片段。例如要"获取特定电影的详细信息"，可能需要提供movie_id；要"搜索人物"，可能需要提供person_name。
- RestGPT如何使用：RestGPT了解需要提供什么信息才能成功执行操作。它也知道某个输入是可选还是必需的。
输出(响应)：
- 定义：操作执行后，说明书描述了你会得到的"菜品"或信息类型。如果你"获取特定电影的详细信息"，说明书会明确你将收到电影的title、release_date和overview。
- RestGPT如何使用：RestGPT理解预期会返回什么类型的数据，从而能够处理并以有用的方式向你呈现信息。

本质上，OAS提供了一种描述API的通用语言，使RestGPT只需阅读一本说明书就能立即理解如何与新的在线服务通信。

RestGPT如何使用OpenAPI规范(底层实现)

让我们看看RestGPT实际是如何读取和使用这些"说明书"的。

整个过程大致如下：

在这里插入图片描述

现在，让我们看看实现这一功能的代码片段。

1. 加载原始规范：

当RestGPT启动时，首先加载完整的原始OpenAPI规范文件。这些文件通常是JSON格式。例如对于TMDB，它会加载specs/tmdb_oas.json。

# 来自run.py
import json
from utils import reduce_openapi_specdef main():# ...(第1章的配置设置)...# 加载完整的原始说明书(OpenAPI规范)with open("specs/tmdb_oas.json") as f:raw_tmdb_api_spec = json.load(f) # 读取整个TMDB API说明书# ...(main函数的其余部分)...

解释：这段简单代码打开tmdb_oas.json文件并将其全部内容读入raw_tmdb_api_spec变量。此时，raw_tmdb_api_spec包含所有细节，包括许多RestGPT不会立即需要的部分。

2. 简化规范：

完整的OpenAPI规范可能非常庞大，包含许多对RestGPT语言模型大脑没有直接用处的技术细节。为了让RestGPT更容易理解和处理，使用了一个特殊函数reduce_openapi_spec来简化它。可以想象为从完整说明书中只提取最重要的"食谱卡片"。

# 来自run.py
# ...(前面的代码)...def main():# ...(加载raw_tmdb_api_spec)...# 简化说明书，只保留RestGPT需要的部分# 想象为只提取相关的食谱卡片api_spec = reduce_openapi_spec(raw_tmdb_api_spec, only_required=False)# 现在，'api_spec'保存了API功能的简洁紧凑版本。# RestGPT将使用这个简化的'api_spec'来理解如何与TMDB对话。# ...(main函数的其余部分)...

解释：reduce_openapi_spec函数接收raw_tmdb_api_spec并进行处理。结果存储在api_spec中，这是一个名为ReducedOpenAPISpec的自定义类对象。这个api_spec就是RestGPT智能组件实际会使用的内容。

让我们看看utils/oas_utils.py中这个ReducedOpenAPISpec和reduce_openapi_spec函数的简化视图：

# 来自utils/oas_utils.py(简化版)
from dataclasses import dataclass
from typing import List, Tuple, Union, Dict, Any@dataclass
class ReducedOpenAPISpec:"""API的简化说明书"""servers: List[dict] # 发送请求的位置(如API地址)description: str    # API的总体描述endpoints: List[Tuple[str, Union[str, None], Dict[str, Any]]] # "食谱卡片"(操作)def reduce_openapi_spec(spec: dict, **kwargs) -> ReducedOpenAPISpec:"""获取完整的OpenAPI规范(说明书)并简化为RestGPT可用的形式。它提取关键信息如：- 所有可用的API操作(如"GET /movie/{movie_id}")。- 每个操作的功能(描述)。- 需要什么输入(参数)。- 会给出什么输出(响应)。"""# ...(复杂的解析和简化逻辑在这里)...# 这个函数筛选有用的操作(如GET、POST)# 并为每个操作提取相关细节：# 参数、描述和简化的响应模式。# 简化后'endpoints'的可能示例：simplified_endpoints_example = [("GET /movie/{movie_id}", "获取特定电影的详细信息", {"parameters": [...], "responses": {...}}),("GET /search/movie", "按名称搜索电影", {"parameters": [...], "responses": {...}}),# ...更多简化的端点描述]return ReducedOpenAPISpec(servers=[{"url": "https://api.themoviedb.org/3"}], # API的基础URLdescription="The Movie Database (TMDB) API",endpoints=simplified_endpoints_example # 简化食谱卡片列表)

解释：ReducedOpenAPISpec是一个Python对象，只保存API说明书的核心部分。reduce_openapi_spec函数负责执行这种简化。它会遍历庞大的JSON文件，挑选出RestGPT能使用的操作，并简化它们的描述、参数和预期响应。这使得信息对RestGPT来说更易于理解和推理。

这个简化的api_spec对象随后被传递给核心的RestGPT组件及其子组件，如API选择器和调用器，使它们能够智能地决定使用哪些API操作以及如何与之交互。