Прибуток:
- Може описати базову структуру запиту LLM API (кінцева точка, модель, повідомлення, max_tokens)
- Розуміє різницю між ролями системи, користувача та помічника та історією розмов без збереження стану
- Може читати та інтерпретувати поля (блоки вмісту, stop_reason, usage) повернутої відповіді
У попередніх модулях ми використовували штучний інтелект із вікна чату. Але якщо ви хочете вбудувати ШІ у свій власний продукт, автоматизацію чи робочий процес, інтерфейс чату не допоможе; Вам потрібно підключитися до моделі програмно, тобто за допомогою коду або інструменту автоматизації. Ім’я цього мосту — API (інтерфейс прикладного програмування, контракт, який дозволяє двом програмам спілкуватися за певними правилами). Коли ви закінчите цей розділ, ви знатимете, що являє собою запит API LLM (Large Language Model), що виконують ролі повідомлень і як читати відповідь. Це основа, на якій буде побудовано решту модуля.
Як працює 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, або використовуйте потокове передавання.
Слабка підказка / Сильна підказка
Те саме завдання з двома різними системними підказками:
# СЛАБКОТи помічник. Дайте відповіді на питання.
# СИЛЬНИЙ Ви помічник корпоративної підтримки. Правила: - Покладайтеся виключно на інформацію в наданому документі політики; Якщо її немає в документі, скажіть «У мене немає цієї інформації, я направляю її у відповідний підрозділ». - Відповіді не повинні перевищувати 3 речень, бути формальними та чіткими. - Не запитуйте особисті дані (номер ТК, номер картки) і не повторюйте. - Не вгадуй, коли не впевнений.
Потужна версія; Він визначає обсяг, форму, запас міцності та поведінку в умовах невизначеності. Узгодженість вихідних даних моделі походить безпосередньо від цієї ясності.
Три міні-чохли
Випадок 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` за звичайний рядок: відповідь — список блоків; прочитати текстове поле першого текстового блоку, перевірити його тип перед отриманням content[0] зі сліпим індексом.
- Вбудовування ключа в код: використовуйте змінну середовища (розділ 9).
Глибше: блоки вмісту та відповіді з кількох частин
Розуміння того, чому поле вмісту у відповіді є списком, є фундаментальним для розширених функцій, з якими ви зіткнетеся пізніше. Іноді модель повертає не один блок тексту, а кілька блоків: блок мислення, за яким йде блок тексту; або блок тексту, за яким іде блок використання інструменту. Ось чому сліпо вважати content[0] як «відповідь» крихким. Правильний підхід полягає в тому, щоб переглянути список і відсортувати його за типом: ви збираєте текстовий вміст блоків, поле типу яких є текстом, і обробляєте інші типи (мислення, інструмент) окремо.
На практиці ця відмінність полягає в тому, що ви можете реєструвати міркування моделі (якщо такі є), не відкриваючи їх користувачеві, перенаправляти виклики інструментів на окрему логіку та друкувати лише фактичну відповідь на екрані. У міру просування модуля (особливо в розділах 4 і 11) ви побачите, наскільки корисною є ця структура блоків для перевірки та спрямування вихідних даних.
Ще один практичний момент: ви можете отримати доступ до однієї моделі з платформ різних провайдерів (прямий API, через хмарний провайдер). Хоча адреса кінцевої точки та формат автентифікації можуть змінюватися, основні поняття, такі як ролі повідомлень, відсутність стану та структура відповіді, залишаються незмінними. Отже, основи цього розділу застосовуються незалежно від того, яку платформу ви використовуєте.
Підсумовуючи
Запит LLM API складається з моделі, обмеження виведення та списку повідомлень; ролі (система, користувач, помічник) визначають поведінку моделі. Дзвінки не мають стану: ви переносите контекст із кожним запитом. Відповідь є структурованим об'єктом; Читання та інтерпретація полів вмісту, stop_reason і usage є основою довговічності у виробництві.
Аплікаційне завдання
Виберіть завдання зі своєї професії (наприклад, сортування вхідної електронної пошти, створення коротких резюме). На аркуші паперу: (1) напишіть системну підказку з 4-5 правилами, (2) налаштуйте зразок повідомлення користувача та 2-раундову історію, якщо така є, (3) визначте прийнятне значення для max_tokens і напишіть обґрунтування, (4) перелічіть, які значення stop_reason ви будете обробляти у поверненій відповіді та як.
контрольний список
- [ ] Я можу порахувати три обов’язкові частини запиту (модель, max_tokens, повідомлення).
- [ ] Я можу пояснити різницю між ролями системи, користувача та помічника.
- [ ] Я знаю, що дзвінки не мають статусу і що мені потрібно зберегти минуле.
- Я можу читати та коментувати [ ] вміст, stop_reason і поля використання.
- [ ] За допомогою max_tokens я можу помітити та обробити скорочену відповідь.