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-агентов к серверу MinerU MCP Server. Это позволяет использовать возможности парсинга документов непосредственно из интерфейсов, поддерживающих MCP (например, Claude Desktop, Cursor или кастомные агенты).

Ниже описана настройка LiteLLM, управление сессиями и примеры конфигурации.

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

LiteLLM действует как обратный прокси для протокола MCP Streamable HTTP. Он берет на себя управление жизненным циклом сессий (Session ID), что освобождает клиентов от необходимости вручную вызывать initialize.

sequenceDiagram
    participant Client as LLM Agent / UI
    participant LiteLLM as LiteLLM Proxy
    participant MCP as MinerU MCP Server

    Client->>LiteLLM: Call Tool (parse_document)
    Note right of Client: Не знает про Session ID
    
    LiteLLM->>LiteLLM: Создает/Использует Session
    LiteLLM->>MCP: POST /mcp (Initialize if needed)
    MCP-->>LiteLLM: Mcp-Session-Id
    LiteLLM->>MCP: POST /mcp (tools/call)
    Note left of MCP: Обрабатывает файл<br/>Поллинг MinerU
    MCP-->>LiteLLM: Result (Markdown/JSON)
    LiteLLM-->>Client: Response

Настройка LiteLLM

Для интеграции необходимо добавить определение MCP-сервера в конфигурационный файл LiteLLM (config.yaml).

Базовая конфигурация

Добавьте секцию mcp_servers в ваш config.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
    transport: streamable_http

Параметры подключения

Параметр	Описание	Пример значения
name	Идентификатор сервера в LiteLLM	mineru_parser
url	Адрес MCP-сервера	http://host.docker.internal:8001
transport	Тип транспорта	streamable_http

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

Управление сессиями

Протокол MCP Streamable HTTP требует наличия активной сессии для выполнения инструментов. LiteLLM автоматизирует этот процесс:

1. Инициализация: При первом обращении к инструменту LiteLLM отправляет запрос initialize на MCP-сервер.
2. Хранение ID: LiteLLM сохраняет полученный заголовок Mcp-Session-Id.
3. Ротация: Запросы к инструментам (tools/call) отправляются с этим ID.
4. Обновление: Если сессия истекает или сервер возвращает ошибку авторизации, LiteLLM может инициировать повторную инициализацию.

Это означает, что клиентам (LLM-агентам) не нужно беспокоиться о создании сессий — они просто вызывают инструменты.

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

Вызов через OpenAI SDK (после настройки LiteLLM)

Если LiteLLM настроен как прокси для OpenAI-совместимых моделей, вы можете вызывать инструменты MCP стандартным образом.

import os
from openai import OpenAI

# Указываем базу LiteLLM
client = OpenAI(api_key="sk-xxx", base_url="http://localhost:4000")

# Пример вызова (зависит от реализации агента, поддерживающего MCP)
# Обычно агенты сами резолвят инструменты, объявленные в MCP-сервере

Ручное тестирование через cURL

Для отладки взаимодействия между LiteLLM и MCP-сервером можно использовать cURL. Однако помните, что LiteLLM скрывает детали сессий от конечного пользователя. Чтобы проверить сам MCP-сервер напрямую (как описано в разделе Тестирование), вам потребуется вручную управлять Mcp-Session-Id.

Безопасность и Авторизация

Если на MCP-сервере включена защита через API Key (переменная MCP_API_KEY в Конфигурации), LiteLLM должен передавать этот ключ в заголовках запросов.

Пример настройки заголовков в LiteLLM (если поддерживается вашим версией/конфигуром):

mcp_servers:
  - name: mineru_parser
    url: http://host.docker.internal:8001
    transport: streamable_http
    # Примечание: Проверьте документацию LiteLLM для передачи custom headers
    # Некоторые версии требуют настройки на уровне прокси-запросов

В текущей реализации МинерU MCP Server авторизация проверяется через middleware AuthMiddleware в файле main.py. Если ключ не передан или неверен, сервер вернет 401 Unauthorized.

Устранение неполадок

Ошибка: Connection Refused

• Причина: LiteLLM не может достичь MCP-сервера.
• Решение: Проверьте URL в config.yaml. Если сервисы в разных сетях Docker, убедитесь, что они находятся в одной сети или используйте host.docker.internal для доступа к хосту.

Ошибка: Missing session ID

• Причина: LiteLLM не смог инициализировать сессию или потерял Session ID.
• Решение: Перезапустите LiteLLM. Проверьте логи MCP-сервера на наличие ошибок при инициализации.

Ошибка: Tool not found

• Причина: Инструмент parse_document не обнаружен.
• Решение: Убедитесь, что MCP-сервер запущен и отвечает на запрос tools/list. Инструмент определен в файле mcp_tools.py.

Связанные ресурсы

• Обзор проекта — Общая информация о MinerU MCP Server.
• Конфигурация — Настройка переменных окружения MCP-сервера.
• Документация API — Детали инструмента parse_document.
• Устранение неполадок — Общие проблемы и их решения.