Печалби:
- Може да опише основната структура на LLM API заявка (крайна точка, модел, съобщения, max_tokens)
- Разбира разликата между ролите на системата, потребителя и асистента и хронологията на разговорите без състояние
- Може да чете и интерпретира полета (блокове със съдържание, stop_reason, използване) на върнатия отговор
В предишните модули използвахме изкуствен интелект от прозорец за чат. Но ако искате да вградите AI във вашия собствен продукт, автоматизация или работен процес, интерфейсът за чат няма да ви помогне; Трябва да се свържете с модела програмно, тоест с код или инструмент за автоматизация. Името на този мост е API (интерфейс за програмиране на приложения, договорът, който позволява на два софтуера да си говорят с определени правила). Когато завършите този модул, ще знаете какво представлява LLM (Large Language Model) API заявка, какво правят ролите на съобщенията и как да прочетете отговора. Това е основата, върху която ще бъде изградена останалата част от модула.
Как работи API?
Основният поток в API е следният: изпращате заявка в определен формат; Сървърът връща отговор в определен формат. В LLM това обикновено е HTTP повикване (HTTP: стандартен протокол за пренасяне на заявка-отговор в мрежата) до един адрес (крайна точка, фиксираният адрес на сървъра, който обработва вашата заявка). Например в API за съобщения всички заявки отиват до един адрес и се пренасят в тялото като JSON (JavaScript Object Notation — текстов формат, състоящ се от двойки ключ/стойност, които могат да се четат както от хора, така и от машини).
В заявка посочвате поне тези три неща:
- Модел: Кой модел ще използвате (напр. бърз и евтин модел или мощен модел).
- max_tokens: Максималният брой токени (най-малката единица, в която се обработва текстът, която ще бъде обработена подробно в следващата единица), които моделът може да произведе; т.е. ограничение на изхода.
- съобщения: Списък със съобщения, съставляващи разговора.
Стъпка по стъпка: Как да настроите заявка
- Подгответе крайната точка и идентификационните данни. Добавяте своя API ключ (тайния низ, който доказва вашата самоличност) към заявката в заглавката. Никога не вграждате ключа в кода; Ние ще покрием безопасното съхранение в блок 9.
- Изберете модела и ограничението на мощността. Лек модел + малки макс_токени за проста задача; Мощен модел + по-голям лимит за сложна задача.
- Настройте списъка със съобщения. 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 изречения, да бъдат официални и ясни. - Не искайте лични данни (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` с обикновен низ: Отговорът е списък от блокове; прочетете текстовото поле на първия текстов блок, проверете неговия тип, преди да получите content[0] със сляп индекс.
- Вграждане на ключа в кода: Използвайте променлива на средата (единица 9).
По-дълбоко: Блокове със съдържание и отговори от няколко части
Разбирането защо полето за съдържание в отговора е списък е фундаментално за разширените функции, които ще срещнете по-късно. Понякога моделът връща не един блок текст, а няколко блока: блок мислене, последван от блок текст; или блок от текст, последван от блок за използване на инструмент. Ето защо сляпото броене на съдържание [0] като „отговор“ е крехко. Правилният подход е да преминете през списъка и да го сортирате по тип: събирате текстовото съдържание на блокове, чието поле за тип е текст, и третирате другите типове (мислене, инструмент) отделно.
Това разграничение на практика е, че можете да регистрирате разсъжденията на модела (ако има такива), без да ги разкривате на потребителя, да пренасочвате извикванията на инструмента към отделна логика и да отпечатвате само действителния отговор на екрана. С напредването на модула (особено в модули 4 и 11) ще видите колко полезна е тази блокова структура за валидиране и насочване на изхода.
Друг практически момент: можете да получите достъп до един и същ модел от различни платформи на доставчици (директен API, чрез облачен доставчик). Въпреки че адресът на крайната точка и форматът за удостоверяване може да се променят, основните понятия като роли на съобщенията, липса на гражданство и структура на отговора остават същите. Така че основите в този модул се прилагат независимо каква платформа използвате.
В обобщение
Заявката за API на LLM се състои от модел, ограничение на изхода и списък със съобщения; ролите (система, потребител, асистент) определят поведението на модела. Обажданията са без състояние: вие носите контекста с всяка заявка. Отговорът е структуриран обект; Четенето и интерпретирането на полетата за съдържание, stop_reason и usage е в основата на издръжливостта в производството.
Задача за приложение
Изберете задача от собствената си професия (напр. сортиране на входяща електронна поща, създаване на кратки резюмета). На лист хартия: (1) напишете подканата на системата с 4-5 правила, (2) настройте примерно потребителско съобщение и двукратна история, ако има такава, (3) определете разумна стойност за max_tokens и напишете обосновката, (4) избройте кои стойности stop_reason ще обработвате във върнатия отговор и как.
контролен списък
- [ ] Мога да преброя трите задължителни части на заявка (модел, max_tokens, съобщения).
- [ ] Мога да обясня разликата между ролите на системата, потребителя и асистента.
- [ ] Знам, че обажданията са без гражданство и че трябва да нося миналото.
- Мога да чета и коментирам [ ] съдържание, stop_reason и полета за използване.
- [ ] С max_tokens мога да забележа и да обработя съкратения отговор.