OpenAI GPT Actions 入门

Weather.gov 示例

美国国家气象局（National Weather Service，NWS）维护一个公共 API，用户可根据经纬度查询天气预报。获取预报分两步：

向 api.weather.gov/points 提供经纬度，获得 WFO（天气预报办公室）标识及网格坐标 grid-X、grid-Y。
将这三个值传入 api.weather.gov/forecast 对应的预报调用，取得该坐标的天气预报。

本练习构建一个自定义 GPT：用户提供城市、地标或经纬度后，GPT 回答该地点的天气预报问题。

第一步：编写并测试 OpenAPI Schema（使用 Actions GPT）

GPT Action 需要 OpenAPI Schema 描述 API 调用参数。OpenAPI 是描述 API 的标准。

OpenAI 提供了公开的 Actions GPT协助编写。可以向它提出：

访问 https://www.weather.gov/documentation/services-web-api ，阅读该页面文档。为 /points/{latitude},{longitude} 和 /gridpoints/{office}/{gridX},{gridY}/forecast 两个 API 调用生成 OpenAPI Schema。

向 Actions GPT 请求生成描述

以下是 Actions GPT 返回的完整 OpenAPI Schema：

来源示例 1（yaml）：

## [中文] 天气服务的完整OpenAPI描述：先按经纬度获取网格信息，再按office、gridX、gridY读取预报；保留operationId、参数和响应结构。
openapi: 3.1.0
info:
  title: NWS Weather API
  description: Access to weather data including forecasts, alerts, and observations.
  version: 1.0.0
servers:
  - url: https://api.weather.gov
    description: Main API Server
paths:
  /points/{latitude},{longitude}:
    get:
      operationId: getPointData
      summary: Get forecast grid endpoints for a specific location
      parameters:
        - name: latitude
          in: path
          required: true
          schema:
            type: number
            format: float
          description: Latitude of the point
        - name: longitude
          in: path
          required: true
          schema:
            type: number
            format: float
          description: Longitude of the point
      responses:
        "200":
          description: Successfully retrieved grid endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  properties:
                    type: object
                    properties:
                      forecast:
                        type: string
                        format: uri
                      forecastHourly:
                        type: string
                        format: uri
                      forecastGridData:
                        type: string
                        format: uri

  /gridpoints/{office}/{gridX},{gridY}/forecast:
    get:
      operationId: getGridpointForecast
      summary: Get forecast for a given grid point
      parameters:
        - name: office
          in: path
          required: true
          schema:
            type: string
          description: Weather Forecast Office ID
        - name: gridX
          in: path
          required: true
          schema:
            type: integer
          description: X coordinate of the grid
        - name: gridY
          in: path
          required: true
          schema:
            type: integer
          description: Y coordinate of the grid
      responses:
        "200":
          description: Successfully retrieved gridpoint forecast
          content:
            application/json:
              schema:
                type: object
                properties:
                  properties:
                    type: object
                    properties:
                      periods:
                        type: array
                        items:
                          type: object
                          properties:
                            number:
                              type: integer
                            name:
                              type: string
                            startTime:
                              type: string
                              format: date-time
                            endTime:
                              type: string
                              format: date-time
                            temperature:
                              type: integer
                            temperatureUnit:
                              type: string
                            windSpeed:
                              type: string
                            windDirection:
                              type: string
                            icon:
                              type: string
                              format: uri
                            shortForecast:
                              type: string
                            detailedForecast:
                              type: string

ChatGPT 使用顶部的 info，尤其是其中的描述，判断 Action 是否与用户问题相关。

来源示例 2（yaml）：

## [中文] info中的标题、描述和版本用于帮助识别Action用途；这里只是完整Schema的片段，不是单独可执行程序。
info:
  title: NWS Weather API
  description: Access to weather data including forecasts, alerts, and observations.
  version: 1.0.0

后面的 parameters 进一步定义参数。例如，以下内容告诉 ChatGPT：office 指天气预报办公室（WFO）的标识。

来源示例 3（yaml）：

## [中文] office是天气预报办公室标识；此片段说明路径参数的名称、位置、类型及含义。
/gridpoints/{office}/{gridX},{gridY}/forecast:
  get:
    operationId: getGridpointForecast
    summary: Get forecast for a given grid point
    parameters:
      - name: office
        in: path
        required: true
        schema:
          type: string
        description: Weather Forecast Office ID

要点：特别注意 Schema 中的名称和描述。ChatGPT 根据它们理解应调用哪个 API，以及应传入哪个参数。如果字段只允许特定值，还可提供带有清楚类别名称的 enum。

虽然可以直接在 GPT Action 中尝试 Schema，但在 ChatGPT 内部调试可能不够方便。原文建议使用 Postman 等第三方服务，先确认 API 调用正常。Postman 可免费注册，错误信息较详细，支持多种认证方式，也支持直接导入 OpenAPI Schema。

在 Postman 中选择导入 API

第二步：确定认证要求

此天气服务不要求认证，因此当前自定义 GPT 可以跳过认证配置。其他需要认证的 GPT Actions 可选 API Key 或 OAuth。对于常见应用，可向 ChatGPT 询问配置方法。例如，要通过 OAuth 连接 Google Cloud，可附上配置界面截图并提问：

我正在通过 OAuth 连接 Google Cloud，请说明这些输入框分别应该如何填写。

向 ChatGPT 询问 OAuth 配置

ChatGPT 通常能协助说明这五项配置。准备好基础信息后，再用 Postman 或类似服务测试和调试认证。如果报错，可将错误信息提供给 ChatGPT，协助排查。

第三步：创建并测试 GPT Action

接下来创建自定义 GPT。如果从未创建过，可先阅读创建 GPT 指南。

填写名称、描述，并添加用于介绍 GPT 的图片。
进入 Action 区域，粘贴 OpenAPI Schema。编写指令时，记录 Action 名称和 JSON 参数。
添加认证设置。
返回主页面，填写指令。

有效指令有多种写法，关键是让模型能够体现用户偏好。通常包括三部分：

背景（Context）：向模型解释 Action 的作用。
操作指令（Instructions）：说明步骤顺序，引用 Action 名称及需要注意的 API 参数。
补充说明（Additional Notes）：列出其他注意事项。

以下是天气 GPT 的指令示例，注意其中如何引用 Schema 中的 API Action 名称与 JSON 参数：

来源示例 4（）：

中文译释：以下为原文指令的完整中文译释，保留原英文块便于对照；这段内容应填写到GPT指令中，不是终端命令。

背景：用户需要了解特定地点的天气预报。

操作指令：
1. 用户会提供经纬度、一般地点或地标，例如纽约市、白宫。没有提供时，先询问地点。
2. 将一般地点或地标转换为经纬度，必要时浏览网页查找坐标。
3. 运行getPointData，取得gridId、gridX、gridY。
4. 将这些值分别作为office、gridX、gridY传给getGridpointForecast，取得预报。
5. 使用预报回答问题。

补充说明：除非另有要求，默认使用美国气象单位，例如华氏度。用户说“开始吧”或“我应该做什么”时，解释该GPT的用途。

**Context**: A user needs information related to a weather forecast of a specific location.

**Instructions**:
1. The user will provide a lat-long point or a general location or landmark (e.g. New York City, the White House). If the user does not provide one, ask for the relevant location
2. If the user provides a general location or landmark, convert that into a lat-long coordinate. If required, browse the web to look up the lat-long point.
3. Run the "getPointData" API action and retrieve back the gridId, gridX, and gridY parameters.
4. Apply those variables as the office, gridX, and gridY variables in the "getGridpointForecast" API action to retrieve back a forecast
5. Use that forecast to answer the user's question

**Additional Notes**:
- Assume the user uses US weather units (e.g. Fahrenheit) unless otherwise specified
- If the user says "Let's get started" or "What do I do?", explain the purpose of this Custom GPT