Прибыль:
- Может описать базовую структуру запроса LLM API (конечная точка, модель, сообщения, max_tokens).
- Понимает разницу между ролями системы, пользователя и помощника и историей разговоров без сохранения состояния.
- Может читать и интерпретировать поля (блоки контента, stop_reason, использование) возвращаемого ответа.
В предыдущих модулях мы использовали искусственный интеллект из окна чата. Но если вы хотите внедрить ИИ в свой собственный продукт, систему автоматизации или рабочий процесс, интерфейс чата вам не подойдет; Подключаться к модели нужно программно, то есть с помощью кода или средства автоматизации. Имя этого моста — API (интерфейс прикладного программирования, контракт, который позволяет двум программам взаимодействовать по определенным правилам). Когда вы закончите этот модуль, вы будете знать, что представляет собой запрос API LLM (большая языковая модель), какие роли сообщений выполняют и как читать ответ. Это фундамент, на котором будет построена остальная часть модуля.
Как работает API?
Основной поток API таков: вы отправляете запрос в определенном формате; Сервер возвращает ответ в определенном формате. В LLM это обычно HTTP-вызов (HTTP: стандартный протокол для передачи запроса-ответа в Интернете) на один адрес (конечная точка, фиксированный адрес на сервере, который обрабатывает ваш запрос). Например, в API обмена сообщениями все запросы отправляются на один адрес и передаются в теле как JSON (нотация объектов JavaScript — текстовый формат, состоящий из пар ключ/значение, который может быть прочитан как людьми, так и компьютерами).
В запросе вы указываете как минимум эти три вещи:
- Модель: какую модель вы будете использовать (например, быструю и дешевую модель или мощную модель).
- max_tokens: максимальное количество токенов (наименьшая единица, в которой обрабатывается текст, которая будет подробно обработана в следующей единице), которую может создать модель; то есть предел вывода.
- сообщения: список сообщений, составляющих беседу.
Шаг за шагом: как настроить запрос
- Подготовьте конечную точку и учетные данные. Вы добавляете свой ключ API (секретную строку, подтверждающую вашу личность) к запросу в заголовке. Вы никогда не встраиваете ключ в код; Мы рассмотрим безопасное хранение в блоке 9.
- Выберите модель и предел вывода. Облегченная модель + маленькие max_tokens для простой задачи; Мощная модель + больший лимит для сложной задачи.
- Настройте список сообщений. List the system instruction, user message, and past rounds (if any).
- Отправьте запрос и проанализируйте ответ. Прочтите текстовое содержимое, причину остановки и использование токена из возвращенного JSON.
Роли сообщений: система, пользователь, помощник
Разговор состоит из сообщений, расположенных в определенной последовательности, и каждое сообщение имеет свою роль. Роль определяет, как модель обрабатывает этот текст.
Роль
Кто пишет
Цель
система
Разработчик/оператор
Постоянные инструкции, индивидуальность и правила, действующие на протяжении всего разговора
пользователь
конечный пользователь
Текущий вопрос или ввод пользователя
помощник
модель
Ответ, полученный моделью (и предыдущие ответы)
Системная роль доступна в виде отдельного системного поля в теле запроса у большинства провайдеров; пользователь и помощник перечислены в списке сообщений последовательно. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Вы помощник корпоративной службы поддержки. Дайте короткий, формальный и проверенный ответ. Не выдумывайте информацию, в которой вы не уверены.", "messages": [ { "role": "user", "content": "Как мне начать процесс возврата?" } ]}
Речь без гражданства
Вот самое распространенное заблуждение: вызовы LLM API не сохраняют состояние — сервер не сохраняет память между двумя запросами. Модель не помнит ваш предыдущий запрос. Если вы настраиваете многораундовый чат, вам придется повторно отправлять предыдущие раунды с каждым новым запросом. «Память» модели состоит из списка отправленных вами сообщений.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Здравствуйте, меня зовут Дениз." }, { "role": "assistant", "content": "Привет, Дениз, чем я могу тебе помочь?" }, { "role": "user", "content": "Я только что назвал свое имя, ты помнишь?" } ]}
Правильный ответ на третье сообщение зависит от того, отправили ли вы оба предыдущих сообщения. Если вы его не отправите, модель не будет знать «Море» и ответит неправильно. Это тоже напрямую влияет на стоимость: чем дольше разговор, тем больше список, каждый запрос потребляет больше токенов.
Совет: при длительных разговорах суммирование и перемещение старых раундов (сводка + последние несколько раундов) вместо отправки всей истории снижает затраты и сохраняет контекстное окно. Мы углубим это в модулях 6 и 11.
Прочитайте ответ
Когда модель возвращает ответ, вы получаете структурированный объект, а не простой текст. Типичные области:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Чтобы инициировать возврат, перейдите на страницу "Мои заказы" в своем аккаунте..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- содержание: сам ответ; Это список блоков контента. Текстовое поле текстового блока является фактическим ответом.
- stop_reason: Почему модель остановилась. end_turn = естественный конец; max_tokens = завис на пределе вывода (ответ может быть неполным); отказ = отказ по соображениям безопасности. Ваш код всегда должен сначала проверять stop_reason.
- использование: номера входных и выходных токенов. Это основа отслеживания затрат и лимитов.
Внимание: если stop_reason равен max_tokens, ответ не будет завершен. Рассматривать это как «успешный ответ» и показывать пользователю половину текста — одна из самых распространенных ошибок в производстве. Либо увеличьте max_tokens, либо используйте потоковую передачу.
Слабая подсказка / Сильная подсказка
Одна и та же задача с двумя разными системными подсказками:
# WEAKВы помощник. Ответь на вопросы.
# STRONGВы помощник корпоративной службы поддержки. Правила:- Полагайтесь исключительно на информацию, содержащуюся в предоставленном политическом документе; Если ее нет в документе, скажите «У меня нет этой информации, я направляю ее в соответствующее подразделение». - Ответы не должны превышать 3 предложений, быть формальными и ясными. - Не запрашивайте персональные данные (номер TC ID, номер карты) и не повторяйте. - Не гадайте, если не уверены.
Мощная версия; Он определяет объем, форму, запас безопасности и поведение в условиях неопределенности. Последовательность результатов модели напрямую зависит от этой ясности.
Три мини-кейса
Случай 1 — Бот поддержки (ловушка безгражданства). Команда электронной коммерции запустила бота; Когда пользователь сказал «отменить предыдущий заказ», бот «забыл» номер заказа. Причина: они отправляли каждый запрос только с последним сообщением. Решение: в список сообщений добавили последние 6 раундов. Результат: контекст сохранен, но количество входных данных на запрос увеличено с 40 токенов до ~600 токенов — мы рассмотрим урок стоимости в модуле 2.
Случай 2 — Неполное описание контракта. Команда юристов составляла 10-страничные контракты; max_tokens: 300 оставалось низким, резюме обрывались на полуслове. stop_reason каждый раз был max_tokens, но никто не смотрел. увеличено max_tokens до 1500 и добавлена проверка stop_reason; Усеченная суммарная ставка снизилась с 18% до 0%.
Случай 3 — Смешение ролей. Маркетинговая команда записывала все инструкции в сообщение пользователя, оставляя систему пустой. Когда пользовательский ввод смешивался с инструкциями, модель иногда выполняла команду пользователя «забыть предыдущие правила». Они перенесли в систему постоянные правила; Благодаря отделению ввода пользователя от инструкций количество нарушений правил значительно сократилось.
Распространенные ошибки
- Забывание отправить прошлое: считается, что модель «не помнит»; тогда как он является лицом без гражданства. Вы несете контекст.
- Не обращая внимания на `stop_reason`: ответ, остановленный с помощью max_tokens, считается завершенным.
- Встраивание инструкции в `user`: постоянные правила в систему; мгновенный ввод поступает пользователю. Смешение создает уязвимости безопасности.
- Принимаем «контент» за простую строку: ответ — список блоков; прочитайте текстовое поле первого текстового блока, проверьте его тип перед получением content[0] со слепым индексом.
- Встраивание ключа в код: используйте переменную среды (блок 9).
Глубже: блоки контента и ответы, состоящие из нескольких частей
Понимание того, почему поле контента в ответе представляет собой список, имеет фундаментальное значение для расширенных функций, с которыми вы столкнетесь позже. Иногда модель возвращает не один блок текста, а несколько блоков: блок мышления, за которым следует блок текста; или блок текста, за которым следует блок использования инструмента. Вот почему слепо считать контент[0] «ответом» ненадежно. Правильный подход — пройтись по списку и отсортировать его по типам: вы собираете текстовое содержимое блоков, поле типа которых является текстовым, а другие типы (мышление, инструмент) обрабатываете отдельно.
На практике это различие означает, что вы можете регистрировать рассуждения модели (если таковые имеются), не раскрывая их пользователю, перенаправлять вызовы инструментов на отдельную логику и печатать на экране только фактический ответ. По мере изучения модуля (особенно в модулях 4 и 11) вы увидите, насколько полезна эта блочная структура для проверки и управления выводом.
Еще один практический момент: вы можете получить доступ к одной и той же модели с разных платформ провайдера (прямой API, через облачного провайдера). Хотя адрес конечной точки и формат аутентификации могут измениться, основные понятия, такие как роли сообщений, отсутствие состояния и структура ответа, остаются прежними. Таким образом, основы, изложенные в этом модуле, применимы независимо от того, какую платформу вы используете.
В заключение
Запрос LLM API состоит из модели, ограничения вывода и списка сообщений; роли (система, пользователь, помощник) определяют поведение модели. Вызовы не имеют состояния: вы переносите контекст с каждым запросом. Ответ представляет собой структурированный объект; Чтение и интерпретация полей содержимого, stop_reason и использования — это основа долговечности производства.
Задача приложения
Выберите задачу из своей профессии (например, сортировка входящей электронной почты, составление кратких обзоров). На листе бумаги: (1) напишите системное приглашение с 4-5 правилами, (2) настройте образец сообщения пользователя и историю за 2 раунда, если таковая имеется, (3) определите разумное значение для max_tokens и напишите обоснование, (4) перечислите, какие значения stop_reason вы будете обрабатывать в возвращенном ответе и как.
контрольный список
- [ ] Я могу посчитать три обязательные части запроса (модель, max_tokens, сообщения).
- [ ] Я могу объяснить разницу между ролями системы, пользователя и помощника.
- [ ] Я знаю, что звонки не имеют гражданства и что мне нужно нести прошлое.
- Я могу читать и комментировать [ ] содержимое, поля stop_reason и использование.
- [ ] С помощью max_tokens я могу заметить и обработать усеченный ответ.