[RestGPT] OpenAPI规范(OAS)

链接：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。

python 复制代码

# 来自run.py
import json
from utils import reduce_openapi_spec

def 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来简化它。可以想象为从完整说明书中只提取最重要的"食谱卡片"。

python 复制代码

# 来自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函数的简化视图：

python 复制代码

# 来自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的基础URL
        description="The Movie Database (TMDB) API",
        endpoints=simplified_endpoints_example # 简化食谱卡片列表
    )

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

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

结论

现在你已经了解了RestGPT理解广阔在线服务世界的秘密：OpenAPI规范(OAS)。

它充当了清晰、标准化的说明书，详细说明了每个可用操作、其所需输入和预期输出。

通过加载和简化这个规范，RestGPT获得了与外部API智能交互所需的知识。

但知道有哪些 可用操作只是拼图的一部分。接下来，我们将深入探索RestGPT的核心智能：RestGPT智能体，它利用这些知识来规划和执行API调用，以满足你的请求

下一章：RestGPT智能体