scan4llm/.ai/VLM_OFFLOAD.md

Offload to Cloud VLM

Когда применять

Если локальное железо не может выполнить задачу:

• Нет GPU, CPU-инференс >5 минут на страницу
• Модель не помещается в RAM
• Точность локальной модели недостаточна, а fine-tune невозможен

И есть подписка с доступом к VLM по API (OpenCode Go, OpenAI, Anthropic).

Тогда локальный OCR делает быструю «грязную» работу, а сомнительные регионы отправляются в cloud VLM.

Паттерн

Локальный OCR (быстрый, среднее качество)
    │
    ├─ confidence > 0.8 → OK, сохраняем как есть
    │
    └─ confidence < 0.8 → вырезаем bbox из изображения
            │
            ▼
       Cloud VLM API (высокое качество)
            │
            ▼
       Заменяем текст блока

Что отправлять

• Не весь документ — только регион изображения (bbox + padding 5px)
• Формат: base64 JPEG, quality=90
• Prompt: «Извлеки весь текст из этого региона. Сохрани формулы как LaTeX.»
• API: Anthropic Messages (/v1/messages) или OpenAI Chat Completions

Интеграция

class VlmCorrector:
    def __init__(self, image_path: str, model: str = "qwen3.8-max"):
        self._image = cv2.imread(image_path)
        self._model = model
    
    def __call__(self, block: ParsedBlock) -> None:
        # crop bbox → base64 → API call → block.content = result

Через Corrector протокол подключается к общему циклу apply_corrector().

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

API-ключ через .env: OPENCODE_API_KEY=sk-... URL из документации провайдера (для OpenCode Go: https://opencode.ai/zen/go/v1/messages)

Ограничения

• Требует интернет (нарушает offline-требование)
• Задержка API: 5-15s на блок
• Лимиты подписки (OpenCode Go: 160 запросов/5ч для Qwen3.8 Max)
• Стоимость: ~$0.01 за блок (при 200 выходных токенах)

Когда НЕ применять

• Весь документ умещается в RAM и обрабатывается <30s локально
• Нет API-подписки
• Документ содержит конфиденциальные данные (offline-требование)