external models

Внешние модели: настройка API

Страница нужна, когда max должен сам вызвать AI-модель: прочитать текст со сканов и картинок, разобрать, как связаны разговоры, или дописать ответ по шаблону. После неё вы сможете выбрать провайдера, сохранить ключ, задать модель для одной задачи и проверить её на малом объёме.

Несколько слов, которые встретятся ниже:

• Внешняя модель — AI-модель, которая работает на сервере провайдера (например, OpenAI или Anthropic). max отправляет ей данные по сети через API.
• API — способ, которым программа обращается к сервису. Доступ к нему даёт ключ — секрет от провайдера. Цена, лимиты и возможности модели зависят от провайдера.
• Назначение — задача, для которой выбрана модель: models.ocr, models.analysis, models.replies. У каждой задачи могут быть свой провайдер и своя модель.
• Endpoint (base_url) — адрес сервера, к которому идёт запрос.

Это не модель вашего AI-агента. Когда агент сам читает файл, он использует свои инструменты и свою модель, и настройки ниже на это не влияют.

Что можно подключить

Задача	Настройка	Как запускается
OCR изображений и сканов PDF	models.ocr	attachments extract --ocr; нужна модель с поддержкой изображений
Анализ связей разговоров в сохранённых сообщениях	models.analysis	conversations build --analyze; согласие относится к конкретному чату и провайдеру
AI-блок в шаблоне ответа	models.replies	Правило с блоком {% ai %} и отдельным согласием для ответов; см. правила ответов
Общие значения для этих задач	models.default	Используются для полей, которые не заданы у конкретного назначения

Поиск по смыслу настраивается отдельно: embedding_provider, embedding_model и embedding_base_url. Ключи он хранит тем же способом. Подробно — в руководстве по поиску. Голосовые распознаёт отдельная модель речи на вашем компьютере, без API — см. распознавание голосовых.

OpenAI: настроить OCR

Выберите точный идентификатор модели с поддержкой изображений. Пример ниже использует gpt-4o-mini; для другой модели замените значение. Сначала сохраните ключ через скрытый интерактивный ввод, затем настройте назначение:

max personal models text key set openai
max personal config set models.ocr.provider openai
max personal config set models.ocr.model gpt-4o-mini
max config show

Ключ не передаётся аргументом команды и не хранится в поле models файла настроек. Команда key set также принимает секрет через stdin; его должен передать ваш менеджер секретов. Не подставляйте сам ключ в командную строку.

Если base_url не задан и не унаследован из models.default, используется стандартный OpenAI endpoint. Для проверки на небольшом объёме:

max personal attachments extract --chat "Учебная группа" --ocr --concurrency 1 --limit 1 --json

--limit 1 ограничивает число файлов, а не API-вызовов. PDF из нескольких сканированных страниц может потребовать по вызову на каждую страницу. Текстовый PDF или DOCX может обработаться локально, без вызова модели. Число вызовов не равно числу файлов.

Anthropic

Выберите точный id доступной вам модели со зрением; your-vision-model ниже — место для вашего значения, а не готовое имя модели.

max personal models text key set anthropic
max personal config set models.ocr.provider anthropic
max personal config set models.ocr.model your-vision-model
max personal config unset models.ocr.base_url

Последняя команда удаляет прежнее переопределение endpoint, если оно было задано. Если URL также не унаследован из models.default, применяется стандартный адрес Anthropic.

Совместимый сервер или общий шлюз

OpenAI-совместимый endpoint использует адаптер openai, даже если сам сервер принадлежит другому провайдеру. Он должен поддерживать соответствующий API и изображения, а не только текстовые запросы. Настройте URL без ключа, параметров запроса и фрагмента:

max personal config set models.ocr.provider openai
max personal config set models.ocr.model your-vision-model
max personal config set models.ocr.base_url https://gateway.example.org/v1
max personal models text key set gateway.example.org

Для нестандартного endpoint имя ключа — его host, включая порт, если он указан в URL. Само поле base_url не является ключом. Если сервер принимает текст, это ещё не значит, что он читает картинки; проверьте это в документации вашего сервера.

При переходе обратно к стандартному OpenAI endpoint удалите models.ocr.base_url. Текстовый и Anthropic-совместимый API нельзя смешивать только заменой URL: выберите адаптер, соответствующий протоколу сервера.

Профиль, общие значения и один запуск

Команды config set выше меняют выбранный профиль. Укажите его первым словом, например max work config set models.ocr.provider openai, или добавьте --defaults для общих значений. Отдельное назначение можно настроить без изменения остальных: models.ocr.* не заменяет models.analysis.* или models.replies.*.

Каждое поле сначала берётся из переменной окружения, затем из настроек профиля и общих значений. Незаданные поля могут наследоваться из models.default. Например, для одного запуска в POSIX-терминале, используя уже сохранённый ключ:

MAX_MODELS_OCR_PROVIDER=openai MAX_MODELS_OCR_MODEL=gpt-4o-mini max personal attachments extract --chat "Учебная группа" --ocr --limit 1 --json

В PowerShell задайте соответствующие $env:MAX_MODELS_OCR_PROVIDER и $env:MAX_MODELS_OCR_MODEL. MAX_MODELS_OCR_BASE_URL переопределяет endpoint. MAX_OPENAI_API_KEY/OPENAI_API_KEY и соответствующие Anthropic-переменные поддерживаются для ключей; не записывайте значения в примеры и историю команд.

models.ocr.provider off выключает это назначение. Настройки и источник каждого значения показывает config show. Как устроены профили и общие значения — в руководстве по настройке.

Согласие, данные и стоимость

Для OCR явный --ocr разрешает передачу выбранных изображений и страниц сканов настроенной модели; согласие для анализа или автоответов не подменяет этот выбор. OCR не включается автоматически, если агенту не удалось прочитать файл. --offline --ocr несовместимы.

Анализ требует отдельного согласия для чата/провайдера. Автоответы имеют собственное согласие и могут отправлять сообщения: настройка ключа сама по себе не разрешает отправку. Следуйте правилам ответов, прежде чем включать AI-блоки.

API может тарифицировать и изображение, и входной/выходной текст. Проверьте цену и лимиты выбранной модели у провайдера; задайте небольшую область и --limit для первого запуска. Параллельность ускоряет обработку, но не уменьшает количество данных и не гарантирует точность. Плохой скан или неподходящая модель могут дать ошибки даже при успешном HTTP-ответе.

Если вызов не работает

Результат	Что проверить
Провайдер или модель не настроены	config show, поля назначения и наследование из models.default
Ключ отсутствует или провайдер отказал	Правильное имя ключа, профиль, endpoint и доступ к модели; не печатайте ключ для проверки
Сервер не принимает изображения	Совместимость API и vision-возможности выбранной модели
engine-missing для PDF	Локальные unpdf и @napi-rs/canvas; это не ошибка API
Нет или недостаточно текста	Качество и полнота изображения, формат ответа, модель и ограничения OCR
Ограничение частоты	Дождаться разрешённого провайдером времени и повторить отдельный запуск; после 429 новые OCR-вызовы этого запуска прекращаются

Успешные результаты OCR сохраняются для поиска; повтор использует хеш файла и выбранную цель модели. Ошибка не удаляет хороший текст, сохранённый раньше, а текст, который сохранил агент, не перезаписывается. Форматы, зависимости и пределы описаны в руководстве по вложениям.