🌟 OpenAPI Tool Servers
该仓库提供了参考的 OpenAPI Tool Server（工具服务器）实现，使开发人员能够轻松且安全地将外部工具和数据源集成到 LLM 智能体（agents）和工作流中。这些实现专为最大程度的易用性和最小的学习曲线而设计，使用广泛采用的 OpenAPI 规范 作为标准协议。
通过利用 OpenAPI，我们消除了对专有或陌生的通信协议的需求，确保您可以快速且充满信心地构建或集成服务器。这意味着您可以减少花在琢磨自定义接口上的时间，而将更多时间用于构建能够增强您的 AI 应用程序的强大工具。
☝️ 为什么选择 OpenAPI？
-
成熟的标准：OpenAPI 是一种被广泛使用、经过生产验证的 API 标准，得到了数以千计的工具、公司和社区的支持。
-
不重复造轮子：没有额外的文档或专有 Spec 导致的困惑。如果您现在已经构建了 REST API 或使用 OpenAPI，那么您就已经准备就绪了。
-
轻松的集成与托管：在外部 或本地部署您的工具服务器，而无需面对厂商锁定或复杂的配置。
-
专注于强大的安全性：围绕 HTTP/REST API 构建，OpenAPI 原生支持广泛使用的安全通信方法，包括 HTTPS 以及经过充分验证的身份验证标准（OAuth, JWT, API Keys）。
-
面向未来且稳定：OpenAPI 受益于广泛的采用、长期的社区支持以及清晰定义的演进过程。
⚠️ 限制
虽然 OpenAPI 工具对于使用外部服务扩展 Open WebUI 非常强大，但与原生 Python 工具相比，它们存在一些限制：
- 仅限单向事件：OpenAPI 工具可以通过 REST 端点发送状态更新、通知和其他单向事件。Open WebUI 会传递
X-Open-WebUI-Chat-Id和X-Open-WebUI-Message-Id响应头以启用此功能。然而，交互式事件（用户输入提示、确认）仅对原生 Python 工具可用。 - 不支持流式输出：工具响应将作为完整的结果返回，而不是逐个 token 进行流式传输。
如果您需要交互式 UI 反馈（确认、用户输入提示），请考虑将您的工具实现为原生 Python Tool。
✅ 支持的 Spec 规范格式
Open WebUI 根据 OpenAPI 3.x 路径项（path-item）模型来解析工具服务器规范（spec）。该解析器：
- 仅识别八个标准的 HTTP 方法键（
get,put,post,delete,options,head,patch,trace）作为操作。路径下的任何其他键——包括扩展键（x-codeSamples,x-internal等）、summary、description、servers和parameters——在操作发现过程中都将被跳过，因此它们绝不会引起解析错误。 - 遵循 路径级（path-level）的
parameters：在路径级别声明一次的参数适用于该路径下的每个操作。具有相同(name, in)键值对的操作级参数将覆盖路径级参数，这符合 OpenAPI 规范。 - 对路径参数值（替换
{id}）和查询参数值进行 URL 编码，以便正确传输包含空格、/、&、?或其他保留字符的值。 - 在获取 spec 时在 JSON 和 YAML 之间进行平滑回退——
.yaml/.ymlURL 将被解析为 YAML；对于其他格式，在失败时先尝试解析为 JSON，再尝试解析为 YAML。
将 parameters 放置在路径级别、暴露扩展键或依赖路径项元数据字段的 specs 均无需修改即可正常工作。
🚀 快速开始
通过我们在 servers/ 目录中提供的基于 FastAPI 的参考实现，快速开始您的开发。（您可以根据需要将这些示例适配到您偏好的技术栈中，例如使用 FastAPI、FastOpenAPI 或任何其他兼容 OpenAPI 的库）：
git clone https://github.com/open-webui/openapi-servers
cd openapi-servers使用 Bash
# 示例：为一个特定的服务器 'filesystem' 安装依赖
cd servers/filesystem
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --reload应当可以从以下地址访问 filesystem 服务器：http://localhost:8000
文档路径为：http://localhost:8000
使用 Docker
如果您安装了 docker compose，请使用以下命令启动服务器：
docker compose up可以在以下地址访问这些服务：
现在，只需将您兼容 OpenAPI 的客户端或 AI 智能体（agents）指向您的本地或公网部署 URL——没有配置烦恼，也没有复杂的传输。
🌱 Open WebUI 社区
- 对于一般性讨论、技术交流和公告，请访问我们的 社区讨论区 页面。
- 有任何想法或反馈？请提交 Issue！