Ключ уже есть: как проверить первый запрос приложения к Anthropic Messages API через «Провод»
Ключ к Claude API уже есть? Отправьте из приложения один непотоковый HTTP-запрос на совместимый адрес «Провода». Проба пройдена, если при HTTP 200 приложение нашло в массиве content блок с type: text и прочитало в его поле text ровно CHECK-241.
Какие настройки нужны для первого запроса Claude API
Приложение отправляет запрос на совместимый HTTP-адрес «Провода». По руководству для прямого вызова нужен POST https://api.provod.ai/v1/messages, заголовок Authorization: Bearer … и версия anthropic-version: 2023-06-01.
Ответ Messages содержит массив блоков content. Обработчик читает поле type, чтобы выбрать блок с текстом, а затем сравнивает его поле text с эталоном. По руководству «Провода», через совместимый интерфейс могут отвечать поддерживаемые модели разных производителей. Форму ответа в этой пробе задает интерфейс Messages, а конкретную модель приложение указывает в поле model.
С адресом легко ошибиться, когда базовый URL уже лежит в конфигурации. В примере ниже PROVOD_API_BASE содержит https://api.provod.ai, а код сам добавляет /v1/messages. Если вы перенесли базовый адрес из другого клиента и в нем уже есть /v1, сначала проверьте итоговый URL. Два сегмента подряд дадут путь /v1/v1/messages. Если используете в своем HTTP-клиенте полный URL, передавайте его целиком один раз.
Модель указывают по опубликованному id из актуального каталога. Имя в интерфейсе, канонический идентификатор и псевдоним могут отличаться. Например, если коллега скопировал название с карточки модели, по нему еще надо найти то значение, которое каталог предлагает передать в model. Удаление пробелов и замена точек на дефисы новый ID не создают.
Для запуска понадобятся три переменные окружения. Задайте PROVOD_API_BASE со значением https://api.provod.ai, PROVOD_MODEL_ID с выбранным ID и PROVOD_API_KEY с выданным ключом. Передайте ключ тем же способом, которым локальный сервер или тестовая среда получает секреты. Когда процесс не видит переменную, стоит проверить настройки его запуска. Достаточно знать, задано ли значение. Печатать его целиком для этой проверки незачем.
Как отправить один непотоковый запрос из приложения
Для пробы достаточно одного POST с Content-Type: application/json. В теле передаем модель, max_tokens: 64, stream: false и одно сообщение от пользователя. Просьба вернуть CHECK-241 дает короткий эталон, который можно сравнить с результатом в коде.
Запрос намеренно обходится без истории переписки и данных пользователей. Представьте, что первая рабочая операция будет извлекать тему из обращения в поддержку. На реальном тикете модель может вернуть правдоподобную фразу, о которой придется спорить, подходит ли она как тема обращения или получилась слишком общей. С контрольной строкой такой спор исчезает. Приложение либо прочитало заданное значение, либо зафиксировало, на каком шаге проба остановилась.
Сохраните скрипт как check_messages.py и запустите python3 check_messages.py из того же окружения, где заданы три переменные. Скрипт использует стандартную библиотеку Python 3. Строка PASS: HTTP 200, CHECK-241 in a text block означает, что проверку прошел отдельный скрипт. Чтобы проверить приложение, выполните контрольный вызов в его HTTP-клиенте и пропустите ответ через штатный обработчик.
import json import os from urllib.error import HTTPError, URLError from urllib.request import HTTPRedirectHandler, Request, build_opener class NoRedirect(HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, hdrs, newurl): return None def accept_response(status, body): if status != 200: return f"Unexpected HTTP status: {status}" try: message = json.loads(body) except (ValueError, UnicodeError): return "Invalid JSON response" content = message.get("content") if isinstance(message, dict) else None if not isinstance(content, list): return "Missing content array" text_blocks = [ block.get("text") for block in content if isinstance(block, dict) and block.get("type") == "text" ] if not text_blocks: return "Missing text block" if "CHECK-241" not in text_blocks: return "Unexpected control value in text blocks" return None def main(): base_url = os.environ.get("PROVOD_API_BASE", "").rstrip("/") model_id = os.environ.get("PROVOD_MODEL_ID", "") api_key = os.environ.get("PROVOD_API_KEY", "") if not (base_url and model_id and api_key): raise SystemExit("Set PROVOD_API_BASE, PROVOD_MODEL_ID and PROVOD_API_KEY") if base_url != "https://api.provod.ai": raise SystemExit("Use the documented base URL without /v1") payload = { "model": model_id, "max_tokens": 64, "stream": False, "messages": [ {"role": "user", "content": "Верни ровно одну строку: CHECK-241"} ], } request = Request( f"{base_url}/v1/messages", data=json.dumps(payload).encode("utf-8"), headers={ "Authorization": f"Bearer {api_key}", "anthropic-version": "2023-06-01", "Content-Type": "application/json", }, method="POST", ) try: with build_opener(NoRedirect()).open(request, timeout=30) as response: problem = accept_response(response.status, response.read()) except HTTPError as error: raise SystemExit(f"Unexpected HTTP status: {error.code}") from None except (URLError, OSError): raise SystemExit("HTTP response could not be read") from None if problem: raise SystemExit(problem) print("PASS: HTTP 200, CHECK-241 in a text block") if __name__ == "__main__": main()
Таймаут в примере задан для учебного запуска. Значение 30 в вызове HTTP-клиента ограничивает ожидание блокирующих сетевых операций, но не задает гарантированную длительность всего запроса. Для рабочей операции границу ожидания выбирают по тому, сколько времени может ждать вызывающий код. Скрипт выполняет один вызов и возвращает статус переадресации как ошибку, чтобы проверка относилась к адресу из настройки.
max_tokens ограничивает генерацию. Число 64 здесь взято для короткой учебной реплики и не показывает, сколько токенов фактически израсходует запрос. stream: false позволяет прочитать тело целиком как JSON. Если библиотека добавляет свои значения по умолчанию, в первой пробе полезно явно выставить режим, чтобы команда и код приложения проверяли одинаковый формат ответа.
Как принять ответ после HTTP 200
Проба пройдена, если статус равен 200, в массиве content есть элемент с type: text, поле text этого элемента равно CHECK-241. Принимать решение по одному статусу рано. Он появляется до проверки того, что прикладной обработчик смог взять из ответа нужное значение.
Допустим, тестовый запуск вернул такое тело. Это учебный фрагмент, пригодный для локальной проверки функции accept_response.
{ "content": [ {"type": "text", "text": "CHECK-241"} ] }
В этом фрагменте сработает и чтение content[0].text. Но оно связывает обработчик с порядком элементов. В Messages содержимое разбито на блоки. По значению type обработчик определяет, как читать блок. Функция из примера перебирает массив и сравнивает текст только у элементов нужного типа. Такой разбор выдержит смену позиции: критерий относится к содержимому блока, где бы тот ни оказался.
Сравнение учитывает каждый символ. Ответ CHECK-214 показывает, что приложение прочитало текст, но проверка значения провалилась. Строка Вот результат: CHECK-241 тоже провалит пробу. Поиск подстроки в сыром HTTP-теле засчитал бы ответ с предисловием и мог бы найти маркер в поле, которое вообще не предназначено для текста ответа. Условие в коде проверяет равенство целой строки одному из значений в текстовых блоках.
В той же папке сохраните этот фрагмент как check_messages_local.py и запустите python3 check_messages_local.py. Он передает функции два учебных ответа с одинаковым HTTP-статусом и типом блока. Меняется только значение text.
from check_messages import accept_response accepted = accept_response( 200, '{"content":[{"type":"text","text":"CHECK-241"}]}' ) rejected = accept_response( 200, '{"content":[{"type":"text","text":"CHECK-214"}]}' ) assert accepted is None, accepted assert rejected == "Unexpected control value in text blocks", rejected print("CHECK-241: PASS") print(f"CHECK-214: {rejected}")
Первая строка вывода подтверждает приемку CHECK-241. Вторая показывает, почему CHECK-214 отклонен при том же HTTP 200. Если сработает assert, исправьте проверку значения до следующего вызова API. Локальный прогон обходится без ключа и проверяет только разбор ответа. Если у единственного блока заменить type на значение, отличное от text, функция вернет Missing text block, даже когда в поле text стоит CHECK-241.
Где искать сбой, если проба не прошла
Причину сбоя ищут по тому, до какой проверки дошел клиент. Сетевой сбой, HTTP-ответ с другим статусом и разобранный ответ с неверной строкой оставляют разные следы. С записью «API не работает» следующий запуск придется начинать с догадок.
• Скрипт вывел HTTP response could not be read. Это общее сообщение для сетевых ошибок в примере. Если HTTP-клиент приложения отдельно сообщает об ошибке подключения или таймауте чтения, сохраните конкретный тип сбоя в журнале. При ошибке подключения проверьте, может ли тестовая среда разрешить имя хоста и установить соединение. При таймауте чтения сверьте настройки ожидания клиента. По этому сообщению состояние генерации остается неизвестным.
• Приложение получило статус, отличный от 200. Зафиксируйте статус и доступные поля ошибки. Если сервер отклонил авторизацию, отметьте, был ли отправлен заголовок со схемой Bearer. Значение ключа в журнал не добавляйте.
• При HTTP 200 скрипт вывел Invalid JSON response или Missing content array. Для первого сообщения проверьте тип содержимого и убедитесь, что приложение читает тело того же ответа, чей статус записало. Для второго проверьте, есть ли в исходном JSON поле content и является ли оно массивом. Сообщение Missing text block означает, что массив прочитан, но в нем нет элемента с type: text. В этом случае сравните типы блоков в исходном ответе и после преобразования в структуру приложения.
• HTTP 200 есть, блок текста найден, значение отличается. Сначала сравните отправленную инструкцию с учебной. В типовом приложении ее могли дополнить шаблоном, где модель просят отвечать полным предложением. Затем проверьте, что обработчик взял поле text из блока нужного типа и сравнил его без очистки. При отличии результат этого прогона остается отрицательным.
В диагностике легко потерять исходное состояние. Кто-то увеличивает таймаут, меняет модель и исправляет путь, а потом получает успешный ответ и уже не может сказать, какая правка помогла. Для следующего запуска достаточно зафиксировать исходный статус и изменить одну настройку, на которую указывает наблюдение.
Для сопоставления результатов храните время запуска, ID модели, версию API и итог проверки. Когда запускаете пробу из терминала и из приложения, отмечайте, где именно получен каждый результат. Успешный запуск из терминала подтверждает параметры в той среде, из которой его выполнили. Запуск в контейнере с другой конфигурацией даст отдельное наблюдение.
Когда переходить к первой рабочей операции
Положительный результат подтверждает, что на выбранном маршруте при этих параметрах приложение получило и прочитало ожидаемый текст. После этого можно испытать одну рабочую операцию на входе, для которого заранее известен критерий приемки. Например, для извлечения темы подготовьте обезличенное обращение и решите, в каком виде приложение должно передать тему дальше.
Практический следующий шаг зависит от того, что произошло на пробе.
• Прогон с CHECK-241 прошел в тестовой среде приложения. Сохраните рабочие настройки и замените учебную инструкцию одной рабочей, чтобы критерий следующего теста относился уже к результату операции.
• Сам запрос выполняется, а обработчик теряет текстовый блок. Сначала исправьте извлечение по type и прогоните локальный пример, затем повторите запрос с теми же сетевыми настройками.
• При смене модели повторите пробу с той же контрольной строкой. Для потоковой выдачи и вызовов инструментов задайте отдельные критерии приёмки.
• Для оценки расходов и поведения под рабочей нагрузкой понадобятся собственные наблюдения. В учебном запросе известен критерий приемки строки, фактический ответ и данные об использовании появляются при запуске.
Сохраните локальную проверку рядом с обработчиком ответа. После правки разбора запустите ее первой.
Перед запуском на своей модели сверьте первый запрос с руководством „Провода“ по Anthropic Messages API.