Перейти к основному содержимому

❓ Часто задаваемые вопросы

🌐 Вопрос: Почему мой локальный сервер инструмента OpenAPI недоступен из интерфейса WebUI?​

Ответ: Если ваш сервер инструмента работает локально (например, http://localhost:8000), браузерные клиенты могут быть ограничены доступом из-за политик CORS (совместного использования ресурсов между источниками).

Убедитесь, что вы явно включили заголовки CORS на вашем сервере OpenAPI. Например, если вы используете 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 с Swag или 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)
  • Basic Auth

Используйте HTTPS в продуктивной среде для шифрования данных при их передаче и ограничьте конечные точки с помощью соответствующих методов авторизации/аутентификации. Вы можете включить эти механизмы прямо в свою схему OpenAPI с использованием поля securitySchemes.

❓ Вопрос: Какие инструменты я могу создать, используя серверы инструментов OpenAPI?​

Ответ: Если это можно сделать доступным через REST API, вы можете это построить. Общие типы инструментов включают:

  • Операции с файловой системой (чтение/запись файлов, список директорий)
  • Доступ к репозиториям Git и документов
  • Запросы к базам данных или исследование схем
  • Веб-скреперы или обобщители
  • Интеграции с внешними SaaS (например, Salesforce, Jira, Slack)
  • Хранилища памяти, прикрепленные к LLM / компоненты RAG
  • Защитите внутренние микросервисы, доступные вашему агенту

🔌 В: Могу ли я запустить более одного сервера инструментов одновременно?​

О: Конечно. Каждый сервер инструментов работает независимо и предоставляет свою собственную схему OpenAPI. Конфигурация вашего агента может указывать на несколько серверов инструментов, позволяя вам комбинировать их в зависимости от потребностей.

Нет ограничений — просто убедитесь, что каждый сервер работает на своем собственном порту или адресе и доступен для хоста агента.

🧪 В: Как протестировать сервер инструментов перед его подключением к LLM-агенту?​

О: Вы можете протестировать свои OpenAPI серверы инструментов с помощью:

  • Swagger UI или ReDoc (по умолчанию встроены в FastAPI)
  • Postman или Insomnia
  • curl или httpie через командную строку
  • Модуль requests в Python
  • Валидаторы и эмуляторы OpenAPI

После проверки вы можете зарегистрировать сервер инструментов с LLM-агентом или через Open WebUI.

🛠️ В: Могу ли я расширять или настраивать референсные серверы?​

О: Да! Все серверы в директории servers/ созданы как простые шаблоны. Вы можете их форкнуть и изменить, чтобы:

  • Добавить новые конечные точки и бизнес-логику
  • Интегрировать аутентификацию
  • Изменить форматы ответа
  • Подключиться к новым сервисам или внутренним API
  • Развернуть их через Docker, Kubernetes или на любом облачном хостинге

🌍 В: Могу ли я запускать OpenAPI серверы инструментов на облачных платформах, таких как AWS или GCP?​

О: Да. Эти серверы являются обычными HTTP-сервисами. Вы можете развернуть их в виде:

  • AWS Lambda с API Gateway (без сервера)
  • Инстансов EC2 или GCP Compute Engine
  • Kubernetes-сервисов в GKE/EKS/AKS
  • Cloud Run или App Engine
  • Render, Railway, Heroku и других

Просто убедитесь, что они настроены безопасно и доступны публично (или через VPN), если это необходимо агенту или пользователю.

🧪 В: Что, если у меня уже есть существующий сервер MCP?​

О: Прекрасная новость! Вы можете использовать наш MCP-to-OpenAPI Bridge: mcpo, чтобы сделать ваши существующие инструменты, основанные на MCP, совместимыми с OpenAPI API. Больше никаких переписываний и сложностей — просто подключите и начните использовать! 🚀

Если вы уже создали инструменты с использованием протокола MCP, mcpo поможет вам мгновенно открыть совместимость с Open WebUI и любым агентом на базе OpenAPI — ваша работа останется доступной и готовой к будущему.

Посмотрите раздел Bridge to MCP в документации для инструкций по настройке.

Быстрый старт:

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

✨ Вот и все — ваш MCP сервер теперь готов к работе с OpenAPI!

🗂️ В: Может ли один OpenAPI сервер реализовывать несколько инструментов?​

О: Да. Один OpenAPI сервер может предлагать несколько связанных функций, сгруппированных под различными конечными точками. Например, сервер документов может предоставлять поиск, загрузку, OCR и суммирование — все в рамках одной схемы.

Вы также можете полностью разделить функции, создав один OpenAPI сервер на каждый инструмент, если предпочитаете изоляцию и гибкость.

🙋 Есть дополнительные вопросы? Посетите обсуждения на GitHub, чтобы получить помощь и обратную связь от сообщества: 👉 Обсуждения сообщества