跳到主要内容

❓ 常见问题

🌐 问：为什么我的本地 OpenAPI 工具服务器无法从 WebUI 界面访问？​

答：如果您的工具服务器在本地运行（例如 http://localhost:8000），基于浏览器的客户端可能由于 CORS（跨域资源共享）策略而被限制访问。

请确保在您的 OpenAPI 服务器中明确启用 CORS 头部。例如，如果您使用的是 FastAPI，您可以添加

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # or specify your client origin
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

此外，如果 Open WebUI 通过 HTTPS 提供服务（例如 https://yourdomain.com），您的本地服务器必须满足以下条件之一

  • 使用 HTTPS 从同一域访问（例如 https://localhost:8000）。
  • 或者在 localhost (127.0.0.1) 上运行，以允许浏览器为本地开发放宽安全限制。
  • 否则，由于混合内容规则，浏览器可能会阻止从 HTTPS 页面向 HTTP API 发送不安全请求。

为了在生产环境中通过 HTTPS 安全工作，您的 OpenAPI 服务器也必须通过 HTTPS 提供服务。

🚀 问：我的服务器实现需要使用 FastAPI 吗？​

答：不需要！虽然我们的参考实现为了清晰易用而使用 FastAPI 编写，但您可以使用任何能够生成有效 OpenAPI (Swagger) 规范的框架或语言。一些常见的选择包括

  • FastAPI (Python)
  • Flask + Flask-RESTX (Python)
  • Express + Swagger UI (JavaScript/Node)
  • Spring Boot (Java)
  • Go 使用 Swag 或 Echo

关键在于确保您的服务器暴露了一个有效的 OpenAPI schema，并且通过 HTTP(S) 进行通信。为所有端点设置一个自定义的 operationId 非常重要。

🚀 问：为什么选择 OpenAPI 而不是 MCP？​

答：在大多数实际应用场景中，OpenAPI 胜过 MCP，因为它更简单、工具生态更完善、更稳定且对开发者更友好。原因如下

  • ✅ 重用您现有的代码：如果您之前构建过 REST API，那么您大部分工作已经完成——无需重写逻辑。只需定义一个符合规范的 OpenAPI spec，并将您现有的代码作为工具服务器暴露出来。

    使用 MCP，您必须在自定义协议层内重新实现工具逻辑，这会重复工作并增加维护范围。

  • 💼 维护和调试更少：OpenAPI 自然融入现代开发流程。您可以使用 Postman 测试端点，使用内置 API 查看日志，使用成熟的生态系统工具轻松排除故障——而且通常根本无需修改您的核心应用。

    MCP 引入了新的传输层、schema 解析和运行时怪癖，所有这些都必须手动调试。

  • 🌍 基于标准：OpenAPI 在整个科技行业得到广泛采用。其定义良好的结构意味着工具、代理和服务器可以立即互操作，无需特殊的桥梁或翻译。

  • 🧰 更好的工具：存在一个支持 OpenAPI 的完整工具生态系统——自动生成客户端/服务器代码、文档、验证、模拟、测试，甚至安全审计工具。

  • 🔐 一流的安全支持：OpenAPI 原生支持 OAuth2、JWTs、API 密钥和 HTTPS 等功能——使用通用库和标准更容易构建安全的端点。

  • 🧠 更多开发者已经了解它：使用 OpenAPI 意味着您正在使用一个后端团队、前端开发人员、DevOps 和产品工程师都熟悉的语言。无需学习曲线或昂贵的入职培训。

  • 🔄 面向未来且可扩展：OpenAPI 随着 API 标准发展并保持向前兼容。相比之下，MCP 是定制的、实验性的——经常需要随着周围生态系统的变化而进行修改。

🧵 总而言之：OpenAPI 让您可以用更少的精力、更少的代码重复和更少的意外完成更多工作。它是驱动 LLM 工具的一条生产就绪、对开发者友好的途径——无需从头开始重建一切。

🔐 问：如何保护我的 OpenAPI 工具服务器？​

答：OpenAPI 支持行业标准的安全机制，例如

  • OAuth 2.0
  • API 密钥头部
  • JWT (JSON Web Token)
  • Basic Auth（基本认证）

在生产环境中使用 HTTPS 加密传输中的数据，并酌情使用适当的认证/授权方法限制端点访问。您可以使用 `securitySchemes` 字段将这些内容直接包含在您的 OpenAPI schema 中。

❓ 问：使用 OpenAPI 工具服务器可以构建哪些类型的工具？​

答：如果可以通过 REST API 暴露，您就可以构建它。常见的工具类型包括

  • 文件系统操作（读/写文件，列出目录）
  • Git 和文档仓库访问
  • 数据库查询或 schema 探索
  • 网页抓取器或摘要生成器
  • 外部 SaaS 集成（例如 Salesforce, Jira, Slack）
  • LLM 连接的内存存储 / RAG 组件
  • 暴露给您的代理的安全内部微服务

🔌 问：我可以同时运行多个工具服务器吗？​

答：当然可以。每个工具服务器独立运行并暴露自己的 OpenAPI schema。您的代理配置可以指向多个工具服务器，让您根据需要进行混合和匹配。

没有限制——只需确保每个服务器在自己的端口或地址上运行，并且代理主机可以访问到它们。

🧪 问：在将工具服务器链接到 LLM 代理之前如何对其进行测试？​

答：您可以使用以下工具测试您的 OpenAPI 工具服务器

  • Swagger UI 或 ReDoc（FastAPI 默认内置）
  • Postman 或 Insomnia
  • 命令行中的 curl 或 httpie
  • Python 的 requests 模块
  • OpenAPI 验证器和模拟器

验证通过后，您可以将工具服务器注册到 LLM 代理或通过 Open WebUI 进行注册。

🛠️ 问：我可以扩展或定制参考服务器吗？​

答：可以！`servers/` 目录中的所有服务器都构建为简单的模板。您可以 Fork 并修改它们来

  • 添加新的端点和业务逻辑
  • 集成认证功能
  • 更改响应格式
  • 连接新的服务或内部 API
  • 通过 Docker、Kubernetes 或任何云主机部署

🌍 问：我可以在 AWS 或 GCP 等云平台上运行 OpenAPI 工具服务器吗？​

答：可以。这些服务器是普通的 HTTP 服务。您可以将它们部署为

  • 带有 API Gateway 的 AWS Lambda（无服务器）
  • EC2 或 GCP Compute Engine 实例
  • GKE/EKS/AKS 中的 Kubernetes 服务
  • Cloud Run 或 App Engine
  • Render, Railway, Heroku 等

只需确保它们已安全配置，并且如果代理或用户需要，可以公开访问（或通过 VPN 访问）。

🧪 问：如果我有一个现有的 MCP 服务器怎么办？​

答：好消息！您可以使用我们的 MCP 到 OpenAPI 桥接工具：mcpo，现在将您现有的基于 MCP 的工具暴露为与 OpenAPI 兼容的 API 变得前所未有的简单。无需重写，没有麻烦——即插即用！🚀

如果您已经使用 MCP 协议构建了工具，mcpo 可以帮助您立即实现与 Open WebUI 和任何基于 OpenAPI 的代理的兼容性——确保您的辛勤工作完全可用且面向未来。

请查阅文档中可选的“桥接到 MCP”部分，以获取设置说明。

快速开始

uvx mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

✨ 就是这样——您的 MCP 服务器现在已经准备好与 OpenAPI 兼容！

🗂️ 问：一个 OpenAPI 服务器可以实现多个工具吗？​

答：可以。一个单一的 OpenAPI 服务器可以提供多个相关功能，并分组在不同的端点下。例如，一个文档服务器可以提供搜索、上传、OCR 和摘要生成功能——所有这些都包含在一个 schema 中。

如果您喜欢隔离和灵活性，您也可以通过为每个工具创建一个 OpenAPI 服务器来实现完全模块化。

🙋 还有更多问题？请访问 GitHub 讨论区获取帮助和社区反馈
👉 社区讨论