This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Интеграция с LiteLLM

LiteLLM выступает в роли MCP Gateway, проксируя запросы от LLM-агентов к вашему MCP-серверу. Эта интеграция позволяет использовать стандартные интерфейсы чата (Chat Completions API) для вызова инструментов MinerU, скрывая сложность управления сессиями MCP и JSON-RPC протокола.

Назначение

LiteLLM абстрагирует взаимодействие с протоколом Model Context Protocol (MCP). Вместо того чтобы агенту напрямую управлять сессиями (Mcp-Session-Id) и отправлять сырые JSON-RPC запросы, LiteLLM:

1. Автоматически инициализирует сессию MCP при первом запросе.
2. Проксирует вызовы инструментов (например, parse_document) к вашему серверу.
3. Возвращает результаты в формате, понятном LLM.

Архитектура взаимодействия

sequenceDiagram
    participant Agent as LLM Agent
    participant LiteLLM as LiteLLM Gateway
    participant MCPServer as MinerU MCP Server

    Agent->>LiteLLM: Chat Completion Request
    LiteLLM->>MCPServer: Initialize MCP Session
    MCPServer-->>LiteLLM: Session ID & Tools List
    LiteLLM->>Agent: Available Tools Description
    Agent->>LiteLLM: Call Tool parse_document
    LiteLLM->>MCPServer: tools/call JSON-RPC
    MCPServer->>MCPServer: Process File (Internal Polling)
    MCPServer-->>LiteLLM: Tool Result
    LiteLLM-->>Agent: Final Response

Конфигурация LiteLLM

Для настройки проксирования необходимо создать или отредактировать файл конфигурации litellm_config.yaml.

Базовая настройка

Добавьте секцию mcp_servers в ваш YAML-файл:

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

mcp_servers:
  - name: mineru_parser
    url: http://host.docker.internal:8001/mcp
    transport: streamable_http

Параметры конфигурации

Параметр	Описание	Пример значения
name	Идентификатор сервера MCP	mineru_parser
url	Адрес вашего MCP-сервера	http://localhost:8001/mcp или http://mineru-mcp:8001/mcp
transport	Тип транспорта	streamable_http

Примечание по сетям:

• Если LiteLLM запущен на хост-машине (не в Docker), используйте http://localhost:8001.
• Если LiteLLM запущен в Docker-контейнере на том же хосте, где работает MCP-сервер, используйте http://host.docker.internal:8001.
• Если оба сервиса работают в одной Docker-сети, используйте имя контейнера, например http://mineru-mcp:8001.

Запуск LiteLLM

После настройки конфигурации запустите LiteLLM:

litellm --config litellm_config.yaml --port 4000

Пример использования

После запуска LiteLLM вы можете обращаться к нему как к обычному OpenAI-совместимому API. LiteLLM автоматически подставит доступные инструменты из MCP-сервера в системное сообщение или ответит списком инструментов при запросе tools/call.

Запрос через API

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LITELLM_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Извлеки текст из этого документа: https://example.com/report.pdf"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "parse_document",
          "description": "Extract text and structure from documents using MinerU",
          "parameters": {
            "type": "object",
            "properties": {
              "source_type": {"type": "string"},
              "source": {"type": "string"},
              "filename": {"type": "string"}
            },
            "required": ["source_type", "source", "filename"]
          }
        }
      }
    ]
  }'

Примечание: В зависимости от версии LiteLLM, инструменты могут передаваться автоматически из конфигурации mcp_servers, либо их нужно явно указать в запросе, если используется режим функции-вызовов.

Связи с другими модулями

• Конфигурация: Убедитесь, что порт MCP-сервера (MCP_PORT) совпадает с тем, что указан в litellm_config.yaml (по умолчанию 8001).
• Архитектура: LiteLLM взаимодействует с конечной точкой /mcp вашего сервера, которая обрабатывается ASGI-приложением в main.py.
• Документация API: Инструмент parse_document, доступный через LiteLLM, соответствует спецификации, описанной в разделе API Reference.
• Устранение неполадок: Если LiteLLM не может подключиться к MCP-серверу, проверьте доступность URL и правильность заголовков авторизации (если включена MCP_API_KEY).

Важные замечания

1. Управление сессиями: LiteLLM берет на себя управление Mcp-Session-Id. Вам не нужно вручную инициализировать сессию через curl при использовании LiteLLM.
2. Авторизация: Если ваш MCP-сервер защищен ключом (MCP_API_KEY), убедитесь, что LiteLLM передает этот ключ в заголовке Authorization: Bearer <key> при проксировании запросов. Это может требовать дополнительной настройки в конфигурации LiteLLM (через api_base или кастомные заголовки, в зависимости от версии).
3. Таймауты: Поскольку парсинг документов может занимать время, убедитесь, что таймауты HTTP-клиента LiteLLM достаточно велики (больше, чем MCP_TIMEOUT_SECONDS вашего MCP-сервера).