Skip to main content

❓ 常见问题

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

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

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

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 或指定您的客户端源
    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 with Swag or Echo

关键是确保您的服务器公开有效的 OpenAPI 架构，并通过 HTTP(S) 进行通信。 为所有端点设置自定义 operationId 是重要的。

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

答： 在大多数实际场景中，OpenAPI 由于其简单性、工具生态系统、稳定性和开发者友好性而胜过 MCP。原因如下：

  • ✅ 重用您现有的代码：如果您之前构建过 REST API，您基本上已经完成了——您不需要重写逻辑。只需定义符合规范的 OpenAPI 规范并将您当前的代码作为工具服务器公开。

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

  • 💼 更少维护和调试：OpenAPI 自然适合现代开发工作流程。您可以使用 Postman 测试端点，使用内置 API 检查日志，使用成熟生态系统工具轻松排障——通常无需修改核心应用程序。

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

  • 🌍 基于标准：OpenAPI 在整个技术行业中被广泛采用。其明确定义的结构意味着工具、代理和服务器可以立即互操作，无需特殊桥接或转换。

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

  • 🔐 一流的安全支持：OpenAPI 包括对 OAuth2、JWT、API 密钥和 HTTPS 等功能的本地支持——使用通用库和标准构建安全端点变得更容易。

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

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

🧵 总结：OpenAPI 让您用更少的努力、更少的代码重复和更少的意外做更多事情。这是为 LLM 工具提供动力的生产就绪、开发者友好的路径——无需从头重建一切。

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

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

  • OAuth 2.0
  • API 密钥头部
  • JWT（JSON Web Token）
  • 基本身份验证

在生产环境中使用 HTTPS 来加密传输中的数据，并根据需要使用适当的身份验证/授权方法限制端点。您可以使用 securitySchemes 字段直接在您的 OpenAPI 架构中包含这些内容。

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

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

  • 文件系统操作（读/写文件、列出目录）
  • Git 和文档仓库访问
  • 数据库查询或架构探索
  • 网页抓取器或摘要器
  • 外部 SaaS 集成（例如 Salesforce、Jira、Slack）
  • LLM 附加的内存存储 / RAG 组件
  • 向您的代理公开的安全内部微服务

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

答： 绝对可以。每个工具服务器独立运行并公开其自己的 OpenAPI 架构。您的代理配置可以指向多个工具服务器，允许您根据需要混合和匹配。

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

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

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

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

一旦验证，您可以通过 LLM 代理或通过 Open WebUI 注册工具服务器。

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

答： 可以！servers/ 目录中的所有服务器都是简单模板。分叉并修改它们以：

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

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

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

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

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

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

答： 好消息！您可以使用我们的 MCP-to-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 和摘要——全部在一个架构内。

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

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