从OpenAI插件到GPTs Actions：基于Flask构建AI后端服务的完整指南

1. 项目概述与核心价值最近在整理一些旧项目翻到了OpenAI早期推出的ChatGPT插件快速入门项目。虽然官方已经明确表示插件Plugins被GPTs和Actions所取代但这个openai/plugins-quickstart仓库依然是一个极佳的学习样本。它用最精简的代码一个Python文件演示了如何构建一个能与ChatGPT对话的“待办事项列表”服务。对于想理解大模型如何与外部工具交互、或者想自己动手搭建一个AI助手的后端服务的开发者来说这个项目就像一份清晰的“解剖图”价值不在于其功能本身而在于它揭示了背后的通信协议和设计范式。简单来说这个项目实现了一个本地运行的服务器。当你在ChatGPT的插件模式中选择“自己开发插件”并指向这个本地服务器时ChatGPT就获得了一个新能力查询和修改你本地的待办事项列表。整个过程涉及几个核心概念插件清单ai-plugin.json定义了插件的基本信息和能力范围OpenAPI规范openapi.yaml像一份详细的API说明书告诉ChatGPT可以调用哪些接口、接口的输入输出是什么而后端服务器main.py则负责实际处理这些请求。通过复现这个项目你能亲手摸清从模型意图理解到API调用再到结果返回的完整链路这是学习AI应用开发非常扎实的第一步。2. 项目架构与核心文件解析这个快速入门项目的结构异常简洁所有核心逻辑都集中在几个文件里。我们先来逐一拆解理解每个文件扮演的角色和它们之间的协作关系。2.1 核心配置文件插件与模型的“契约”一个ChatGPT插件要正常工作必须向ChatGPT提供两份关键的“身份证明”和“能力说明书”它们都以特定名称和格式存放在服务器的根路径下。ai-plugin.json插件的“身份证”这个文件是插件的元数据清单。当ChatGPT尝试连接你的插件时它会首先请求这个文件。其内容定义了插件的基本信息让ChatGPT和用户知道这个插件是干什么的。原项目中的配置非常基础但每一个字段都有其用意schema_version: 遵循的清单格式版本。name_for_human: 展示给用户的插件名称要求简洁易懂。name_for_model: 模型内部识别插件用的名称通常用简短、无空格的标识符。description_for_humandescription_for_model: 分别面向用户和模型的描述。给模型的描述尤为关键它应该清晰说明插件的核心功能和使用场景这直接影响ChatGPT是否以及在何种情境下会调用该插件。auth: 定义认证方式。本例中为none表示无需认证。对于需要访问用户私有数据的生产级插件这里通常会配置OAuth等认证方式。api: 指向OpenAPI规范文件的URL。这是插件能力的“目录”。logo_url: 插件图标。contact_emaillegal_info_url: 联系方式和法律信息。openapi.yamlAPI的“详细说明书”这是OpenAPI规范文件采用YAML格式编写。它严格定义了服务器暴露的所有API端点Endpoint、每个端点支持的HTTP方法GET、POST等、请求参数、请求体格式以及响应结构。ChatGPT的底层系统会解析这份文件从而“学会”如何调用你的服务。openapiinfo: 定义规范版本和API的基本信息。servers: 指定API服务器的基础URL。本地开发时就是http://localhost:5003。paths: 这是核心部分列出了所有可用的API路径。例如/todos路径下定义了get和post操作分别对应获取列表和新增待办项。每个操作下会定义operationId: 操作的唯一标识符。summarydescription: 简要说明和详细描述帮助模型理解何时使用该操作。parameters/requestBody: 定义输入。对于POST /todos它定义了需要一个包含todo字段的JSON对象。responses: 定义各种HTTP状态码下的响应体格式。这确保了ChatGPT能正确解析你返回的数据。这两份文件共同构成了一份完整的“契约”让ChatGPT这个“大脑”能够安全、准确地指挥你的“手”后端服务去执行任务。2.2 后端服务器实现逻辑处理的核心main.py数据与逻辑的承载者这是整个插件的“心脏”一个使用Flask框架构建的轻量级Web服务器。它的核心职责是提供静态文件服务通过/和/.well-known/路由将上述的ai-plugin.json和openapi.yaml文件提供给ChatGPT进行发现和读取。实现业务API实现OpenAPI规范中声明的所有端点这里是/todos的GET和POST操作。维护数据状态在内存中用一个Python列表维护待办事项列表。需要注意的是这只是为了演示服务器重启后数据会丢失。生产环境需要连接数据库。让我们深入看一下关键代码段app.route(‘/todos‘, methods[‘GET‘]) def get_todos(): # 简单地返回整个待办事项列表 return jsonify(todos) app.route(‘/todos‘, methods[‘POST‘]) def add_todo(): # 从请求中获取JSON数据 data request.get_json() todo_item data.get(‘todo‘) if not todo_item: return jsonify({“error“: “‘todo‘ field is required“}), 400 # 生成一个简单的ID并添加到列表 new_id len(todos) 1 new_todo {“id“: new_id, “todo“: todo_item} todos.append(new_todo) return jsonify(new_todo), 201代码逻辑非常直白GET请求返回列表POST请求解析JSON并添加新项。这里体现了后端服务的一个基本原则严格遵循API契约。请求体格式、错误处理如缺少todo字段返回400错误都必须与openapi.yaml中的定义保持一致否则ChatGPT可能会无法理解返回结果。requirements.txt环境依赖清单这个文件列出了运行项目所需的所有Python包。原项目只包含了flask、flask-cors和requests。flask-cors用于处理跨域请求这在本地开发、ChatGPT网页端访问本地服务时是必须的。3. 本地环境搭建与运行实操理解了架构接下来我们动手把项目跑起来。这个过程不仅是简单的复制粘贴我会补充一些实践中容易遇到的细节和原理确保你能一次成功。3.1 基础环境准备与依赖安装首先你需要一个Python环境。我推荐使用Python 3.8或更高版本。为了避免包冲突强烈建议使用虚拟环境Virtual Environment。步骤分解与原理说明克隆或下载项目将openai/plugins-quickstart仓库的代码下载到本地一个目录中。创建并激活虚拟环境# 在项目根目录下 python -m venv venv # 激活虚拟环境 # 在Windows上 .\venv\Scripts\activate # 在macOS/Linux上 source venv/bin/activate激活后你的命令行提示符前通常会显示(venv)表示你正在虚拟环境中工作。这里的所有包安装都只会影响这个隔离的环境。安装依赖pip install -r requirements.txt执行后pip会读取requirements.txt文件依次安装Flask、Flask-CORS等包。你可以通过pip list命令来确认安装是否成功。注意如果遇到安装速度慢或超时是因为默认的PyPI源服务器在国外。可以临时使用国内镜像源加速例如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 启动服务器与关键配置验证依赖安装完成后直接运行主程序即可启动服务器python main.py如果一切正常终端会输出类似以下的信息* Serving Flask app ‘main‘ * Debug mode: off * Running on http://127.0.0.1:5003 (Press CTRLC to quit)这表示一个Flask开发服务器已经在本地5003端口启动。关键检查点启动服务器后不要急着去ChatGPT界面操作。先打开浏览器手动访问以下几个关键端点验证服务器配置是否正确。这是排查后续问题的第一步很多“插件安装失败”都源于此。验证主页面访问http://localhost:5003。你应该能看到一个简单的“TODO Plugin”页面。这证明Flask应用基本路由正常。验证插件清单访问http://localhost:5003/.well-known/ai-plugin.json。浏览器应该会下载或直接显示一个JSON文件内容就是之前分析的插件元数据。检查其格式是否正确特别是api字段的URL是否指向正确的openapi.yaml地址。验证OpenAPI文档访问http://localhost:5003/openapi.yaml。浏览器应显示完整的YAML格式的API文档。确保其内容完整没有语法错误。如果以上任何一步失败例如返回404错误或JSON/YAML解析错误都需要回头检查main.py中的路由设置和文件路径。常见的错误包括文件没有放在项目根目录或者.well-known目录名拼写错误。3.3 在ChatGPT中安装并测试本地插件这是最令人兴奋的一步让你的本地服务与ChatGPT对话。请注意此功能需要你有ChatGPT Plus订阅并且当时在插件测试阶段获得了插件功能权限。由于插件已被GPTs取代新用户可能无法在界面上看到“Plugin store”选项本部分主要作为历史工作流程的讲解。历史工作流程回顾在浏览器中登录https://chat.openai.com。在模型选择下拉框中通常显示为“GPT-4”选择“Plugins”模式。在已安装插件列表下方点击“Plugin store”。在插件商店的右下角点击“Develop your own plugin”。在弹出的对话框中输入你的本地服务器地址http://localhost:5003然后点击“Find manifest file”。此时ChatGPT会向你的本地服务器请求/.well-known/ai-plugin.json文件。如果上一步验证通过这里就会成功读取并安装。安装成功后你会在插件列表中看到“TODO Plugin”被启用。开始测试你可以问“What is on my todo list?” ChatGPT会调用插件的GET接口由于初始列表为空它可能会回复你的待办列表是空的。接着你可以说“Add ‘Buy groceries‘ to my todo list.” ChatGPT会理解你的意图调用POST接口并返回操作成功的确认信息。再次询问待办列表你应该能看到新增的条目。这个交互过程完美展示了ChatGPT作为“智能调度中心”的角色它理解你的自然语言指令将其转化为对特定API的调用获取结果后再用自然语言组织成回复给你。4. 从插件到GPTs Actions的演进与迁移思考虽然这个快速入门项目是针对已“退役”的插件体系但它的核心思想——让大模型安全可控地调用外部工具——在OpenAI新的GPTs和Actions框架中得到了继承和增强。理解这个项目是理解Actions的绝佳基础。4.1 插件模式的局限性与GPTs Actions的改进ChatGPT插件模式存在一些体验上的痛点而GPTs Actions针对这些痛点做了优化发现与安装流程插件需要用户主动去插件商店搜索、安装并手动启用流程较长。而GPTs是用户直接与一个定制化的AI对话其集成的Actions动作是开箱即用的无需额外安装步骤。配置复杂度插件开发需要同时维护ai-plugin.json和openapi.yaml两个配置文件。Actions的配置则完全集成在GPTs的创建流程中本质上还是基于OpenAPI规范但通过GPT创建界面进行可视化配置对开发者更友好。身份与上下文插件是全局的所有对话都可以启用。而GPTs是独立的、有特定身份和指令的AI其集成的Actions与这个GPT的专属能力绑定上下文更清晰。例如你可以创建一个“旅行规划GPT”它集成的Actions专门用于查询航班和酒店用户无需在通用聊天中来回切换插件。4.2 如何将“TODO插件”改造成一个GPT Action假设我们现在要基于这个待办事项服务创建一个名为“个人事务助理”的GPT。迁移改造的核心工作在于调整配置的提供方式而后端服务器main.py的代码几乎可以原封不动地复用。改造步骤确保后端服务可公开访问GPTs Actions要求你的后端服务必须有一个公网可访问的HTTPS地址不能是localhost。你需要将你的Flask应用部署到云服务器如AWS EC2、Google Cloud Run、Heroku或使用内网穿透工具如ngrok、localtunnel临时暴露本地服务。使用ngrok示例在终端运行ngrok http 5003它会给你一个如https://abcd1234.ngrok-free.app的公网地址。将代码中所有localhost:5003的引用替换为此地址。创建GPT并配置Action在ChatGPT界面点击“Explore GPTs” - “Create a GPT”。在“Configure”选项卡中找到“Add Actions”部分。点击“Create new action”你需要填写的信息本质上就是原来ai-plugin.json和openapi.yaml内容的整合Authentication如果你的服务需要认证本例不需要在此处配置。Schema这里就是粘贴你OpenAPI规范的地方。你需要将openapi.yaml的内容或转换成JSON格式粘贴进来。确保其中的serversURL已经更新为你的公网地址例如https://abcd1234.ngrok-free.app。OpenAI的配置界面会实时解析你提供的Schema并列出可用的操作如get_todos,add_todo。你可以为每个操作添加更详细的自然语言描述帮助GPT更好地理解何时调用它。测试与发布保存Action配置后你可以在右侧的预览窗格直接测试。对GPT说“查看我的待办事项”它就会调用你配置的Action。测试无误后即可发布你的GPT。核心不变点无论底层框架叫插件还是Action其技术本质都是基于OpenAPI规范的RESTful API调用。你的后端服务器作为API提供方只要接口符合规范就可以被不同的AI前端所调用。这体现了“关注点分离”的设计优势业务逻辑稳定地驻留在后端前端的交互方式可以随平台演进。5. 开发扩展与实战避坑指南掌握了基础流程后我们可以把这个简单的TODO插件扩展得更实用同时总结一些实战中必然会遇到的“坑”及其解决方案。5.1 功能扩展从内存存储到持久化数据库内存存储显然不适用于真实场景。我们来将其改造成使用SQLite数据库这是一个轻量且无需额外服务的选择。步骤实现修改依赖在requirements.txt中添加sqlite3Python标准库通常无需额外安装或更强大的sqlalchemy用于ORM操作。这里我们用内置的sqlite3。修改main.py初始化数据库和表import sqlite3 from flask import g import os DATABASE ‘todos.db‘ def get_db(): db getattr(g, ‘_database‘, None) if db is None: db g._database sqlite3.connect(DATABASE) # 启用行工厂使返回结果像字典一样访问 db.row_factory sqlite3.Row return db def init_db(): with app.app_context(): db get_db() cursor db.cursor() cursor.execute(‘‘‘ CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY AUTOINCREMENT, todo TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP) ‘‘‘) db.commit()在应用启动时调用init_db()。重写API端点GET /todos: 从数据库SELECT * FROM todos查询数据并返回。POST /todos: 将数据INSERT INTO todos (todo) VALUES (?)插入数据库并返回新创建的行。注意事项连接管理上述代码使用了Flask的g对象来确保每个请求周期内使用同一个数据库连接请求结束后自动关闭。这是Web开发中的常见模式。错误处理数据库操作可能会失败如唯一约束冲突务必添加try...except块并返回适当的HTTP错误码如500和错误信息。数据序列化sqlite3.Row对象不能直接JSON序列化需要转换为字典例如dict(row)。5.2 安全性增强添加API密钥认证对外开放的API必须考虑安全。最简单的防护是使用API Key。实现方案生成并管理密钥可以在服务器启动时生成一个随机密钥或由管理员配置。更安全的方式是为每个用户分配唯一密钥。修改openapi.yaml在components.securitySchemes部分添加API Key认证方案。components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key在需要认证的路径下添加security: - ApiKeyAuth: []。修改main.py在每一个需要保护的端点处理函数开头检查请求头中的X-API-Key是否与预设的密钥匹配。API_KEY “your-secret-api-key-here“ # 应从环境变量读取切勿硬编码 app.before_request def validate_api_key(): # 排除公开的清单和文档端点 if request.path in [‘/‘, ‘/.well-known/ai-plugin.json‘, ‘/openapi.yaml‘]: return provided_key request.headers.get(‘X-API-Key‘) if not provided_key or provided_key ! API_KEY: return jsonify({“error“: “Invalid or missing API key“}), 401app.before_request装饰器使得在每次请求处理前都会执行这个函数进行校验。重要安全提示永远不要将真实的API密钥、密码等敏感信息硬编码在代码中。应该使用环境变量来管理import os API_KEY os.environ.get(“TODO_API_KEY“) if not API_KEY: raise ValueError(“TODO_API_KEY environment variable not set“)在运行服务前通过终端设置环境变量export TODO_API_KEYyour_key(Linux/macOS) 或set TODO_API_KEYyour_key(Windows)。5.3 常见问题排查实录在开发和调试过程中你几乎一定会遇到下面这些问题。这里是我的排查清单问题1ChatGPT提示“无法找到插件清单”或“安装失败”。检查1网络连通性。确保运行ChatGPT的浏览器能访问你的本地服务器。localhost仅限本机访问。如果你在虚拟机或容器内运行服务器需使用宿主机的IP。检查2CORS头。确保flask-cors已正确安装并在main.py中启用CORS(app)。浏览器会因同源策略拦截跨域请求。检查3清单文件可访问。直接在浏览器中访问http://你的服务器地址/.well-known/ai-plugin.json确认能返回正确的JSON内容且api.url字段指向的openapi.yaml地址同样可访问。检查4HTTPS要求。某些阶段的ChatGPT可能要求插件使用HTTPS。本地开发时你需要使用工具如ngrok提供HTTPS隧道或为Flask配置SSL证书来提供HTTPS服务。问题2ChatGPT能安装插件但对话时不调用。检查1模型描述。仔细检查ai-plugin.json中的description_for_model字段。这个描述至关重要它决定了ChatGPT在什么情况下认为需要调用你的插件。描述应清晰、简洁包含关键动词和名词如“管理用户的待办事项列表”。检查2OpenAPI规范。检查openapi.yaml中每个操作的description。这些描述同样会帮助模型理解每个API的具体用途。检查3用户指令清晰度。尝试使用更直接、无歧义的语言例如直接说“使用TODO插件查看我的列表”而不是“我有什么事情要做吗”。问题3插件被调用但返回错误或意外结果。检查1服务器日志。查看运行python main.py的终端输出这里有最详细的错误信息如500内部错误、404未找到等。检查2API请求/响应格式。使用浏览器开发者工具的网络Network选项卡或使用Postman等工具模拟ChatGPT发送的请求。对比请求体、请求头是否与openapi.yaml中的定义完全一致。检查你的后端代码是否返回了正确格式的JSON。检查3数据验证。你的后端是否对输入数据进行了充分的验证和清理例如POST请求是否检查了必要字段的存在性是否处理了字段类型错误问题4部署到公网后Action不工作。检查1防火墙与安全组。确保云服务器的安全组Security Group或防火墙规则允许外部访问你应用监听的端口如5003。检查2进程管理。Flask开发服务器app.run()仅用于开发不支持并发且不稳定。生产环境应使用WSGI服务器如Gunicorn或uWSGI。pip install gunicorn gunicorn -w 4 -b 0.0.0.0:5003 main:app检查3反向代理与HTTPS。生产环境通常在前端使用Nginx或Apache作为反向代理处理HTTPS、静态文件和负载均衡。确保你的WSGI服务器通过反向代理正确暴露。通过这个从简到繁、从本地到部署的完整过程你不仅复活了一个“过时”的示例项目更实质性地掌握了构建AI后端服务的核心技能。这套技能——设计清晰的API、编写健壮的后端逻辑、处理认证与安全、进行部署和调试——是当前AI应用开发中不可或缺的基石。无论前端是ChatGPT插件、GPTs Action还是其他任何大模型平台其与外部世界交互的方式万变不离其宗。