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

Это руководство помогает подключить модель к CLI: выбрать провайдера, сохранить ключ, задать модель для конкретной задачи и запустить её явно. Здесь модель вызывается через API, а не средствами самого агента; её доступность, цена и возможности зависят от провайдера.

Какие задачи используют APICopy Anchor Link

Смысловой поиск использует отдельные настройки embeddingProvider, embeddingModel и embeddingBaseUrl, но может использовать тот же механизм хранения ключей. См. поиск. Голосовые распознаются отдельной локальной моделью речи; см. распознавание голоса.

Настройка models.ocr не выбирает модель вашего агента. Когда агент читает файл своими средствами, используются его собственные инструменты и модель.

OpenAI: настроить OCRCopy Anchor Link

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

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

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

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

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

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

AnthropicCopy Anchor Link

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

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

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

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

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

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

Для нестандартного endpoint имя ключа — его host, включая порт, если он указан в URL. Само поле baseUrl не является ключом. Поддержка обычных текстовых запросов сервером ещё не означает поддержку vision OCR; проверьте это в документации вашего сервера.

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

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

Команды 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 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. Полная справка: настройки.

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

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

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

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

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

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