Prompt engineering в Python: шаблон, роля и примери

Проблем

Отговорът, който звучи добре

Клиент пише в чата на магазина: „Кога ще пристигне поръчка 1042?“. Асистентът е свързан с модел като в урока за извикването на API, а системният промпт е един ред:

client = FakeClient()
order = Order("1042", "изпратена", "03.11")
question = [{"role": "user", "content": "Кога ще пристигне поръчка 1042?"}]
reply = client.create("Ти си асистент на магазин.", question)
print(f"промпт: ~{reply['input_tokens']} токена")
print(f"отговор: {reply['text']}")
for line in check(reply["text"], order):
    print(f"  {line}")

промпт: ~14 токена
отговор: Здравейте! Благодаря, че се свързахте с нас. Обикновено доставката отнема от 2 до 5 работни дни според куриера и адреса. Поръчка 1042 най-вероятно ще пристигне до петък. Ако имате още въпроси, с удоволствие ще помогна!
  ✗ до 30 думи (35)
  ✗ датата от данните (03.11)
  ✓ номерът на поръчката (1042)

Отговорът е учтив, но е 35 думи, когато в чата се събират две изречения. Срокът „от 2 до 5 работни дни“ е общ, а „до петък“ е измислен: в базата поръчката пристига на 03.11. Клиентът ще чака в петък, а после ще пише пак, ядосан.

Моделът не е сбъркал нищо, което може. Той не знае нищо за поръчка 1042 и дописва най-правдоподобния текст, както в урока за границите на модела. Проблемът е в промпта.

Идеята

Промптът е спецификация

Промптът казва на модела какво да направи, както задачата казва на нов колега. Добрият промпт има пет части:

Роля: кой е моделът („асистент на поддръжката на магазина“).
Правила: колко дълго, на какъв тон, какво не бива.
Данни: всичко, което моделът трябва да знае, сложено от програмата. Тук това е поръчката от базата.
Граница на данните: тагове като <order> и </order> показват къде свършват инструкциите и къде започват данните.
Какво прави, когато не знае: „ако данните не стигат, предай на колега“. Без това правило моделът запълва празното с измислица.

Промптът се сглобява от функция с параметри, а не се пише на ръка за всеки въпрос. Тази функция е шаблон на промпта (prompt template). Писането и изпитването на такива промпти е prompt engineering: промптът е код, който моделът изпълнява.

Виж го

Шаблонът

Шаблонът взима поръчката и връща системния промпт:

def support_prompt(order):
    return f"""Ти си асистент на поддръжката на магазина.
Отговаряй на „Вие“, с най-много две изречения.
Ползвай само данните между <order> и </order>.
Ако данните не стигат, предай на колега.
Не обещавай срокове извън данните.

<order>
номер: {order.id}
статус: {order.status}
очаквана доставка: {order.eta}
</order>"""

order = Order("1042", "изпратена", "03.11")
system = support_prompt(order)
print(system)
print(f"~{tokens(system)} токена")

Ти си асистент на поддръжката на магазина.
Отговаряй на „Вие“, с най-много две изречения.
Ползвай само данните между <order> и </order>.
Ако данните не стигат, предай на колега.
Не обещавай срокове извън данните.

<order>
номер: 1042
статус: изпратена
очаквана доставка: 03.11
</order>
~55 токена

Данните не идват от модела, а от програмата: статусът и датата са прочетени от базата. Ако поръчката утре смени статуса си, промптът се сменя с нея.

Цената: неясният промпт беше около 7 токена, този е около 55. Всеки въпрос в чата плаща тези токени наново, защото API-то няма памет и промптът тръгва с всяка заявка. Какво е токен и защо цената е в токени, видя в урока за токените.

Виж го

Един въпрос, два промпта

vague = "Ти си асистент на магазин."
prompts = [vague, support_prompt(order)]
for system in prompts:
    reply = client.create(system, question)
    print(f"~{reply['input_tokens']} токена")
    print(reply["text"])
    for line in check(reply["text"], order):
        print(f"  {line}")

def support_prompt(order):
    return f"""Ти си асистент на поддръжката на магазина.
Отговаряй на „Вие“, с най-много две изречения.
Ползвай само данните между <order> и </order>.
Ако данните не стигат, предай на колега.
Не обещавай срокове извън данните.

<order>
номер: {order.id}
статус: {order.status}
очаквана доставка: {order.eta}
</order>"""

Стъпка по стъпка, с думи

Един въпрос от клиент: „Кога ще пристигне поръчка 1042?“ Първо неясният промпт: един ред, без данни, ~14 токена.
Отговорът е учтив и дълъг. „До петък“ е измислено: в промпта няма дата, от която моделът да вземе срока.
Програмата проверява отговора: 35 думи, няма датата от данните. Минава 1 от 3.
Шаблонът: кой е моделът, колко дълго да отговаря, какво може да ползва и какво да прави, когато данните не стигат.
Данните на поръчката идват от програмата, между <order> и </order>. Промптът вече е ~62 токена вместо ~14.
Същият въпрос, новият промпт: едно изречение с датата 03.11.
Неясният промпт минава 1 проверка от 3, ясният 3 от 3. Ясният промпт е по-дълъг, но отговорът му може да се провери.

Програмата праща един и същ въпрос с двата промпта и проверява всеки отговор с три правила: дължина, датата от данните и номерът на поръчката:

def check(answer, order):
    words = len(answer.split())
    return [
        f"{mark(words <= 30)} до 30 думи ({words})",
        f"{mark(order.eta in answer)} датата от данните ({order.eta})",
        f"{mark(order.id in answer)} номерът на поръчката ({order.id})",
    ]


def mark(ok):
    return "✓" if ok else "✗"

client = FakeClient()
order = Order("1042", "изпратена", "03.11")
question = [{"role": "user", "content": "Кога ще пристигне поръчка 1042?"}]
vague = "Ти си асистент на магазин."
prompts = [vague, support_prompt(order)]
for system in prompts:
    reply = client.create(system, question)
    print(f"~{reply['input_tokens']} токена")
    print(reply["text"])
    for line in check(reply["text"], order):
        print(f"  {line}")

~14 токена
Здравейте! Благодаря, че се свързахте с нас. Обикновено доставката отнема от 2 до 5 работни дни според куриера и адреса. Поръчка 1042 най-вероятно ще пристигне до петък. Ако имате още въпроси, с удоволствие ще помогна!
  ✗ до 30 думи (35)
  ✗ датата от данните (03.11)
  ✓ номерът на поръчката (1042)
~62 токена
Поръчка 1042 е изпратена и се очаква да пристигне на 03.11.
  ✓ до 30 думи (11)
  ✓ датата от данните (03.11)
  ✓ номерът на поръчката (1042)

Неясният промпт минава 1 проверка от 3, ясният 3 от 3. Проверките са код: те не казват дали отговорът е хубав, а дали спазва правилата, които можеш да провериш. Как такива проверки стават тестов набор за цялото приложение, е в урока за оценяването.

Честно за модела в програмите. Тук моделът е фалшив клиент: същата форма като истинското API (системен промпт, съобщения, отговор и токени), но отговорите са записани. Правилото му е грубо: ако в промпта има данни за поръчка, отговаря от тях; ако няма, връща типичния общ отговор. Така програмата върви без мрежа и дава едно и също всеки път. Истински модел ще даде други думи при всяко пускане, но разликата между двата промпта е същата. Кодът на фалшивия клиент е в „По-точно“ най-долу.

Пробвай

Намери грешката

Колега преправя шаблона за въпроса „къде са ми поръчките?“ и подава всички поръчки от базата. Тестовете минават: отговорите са кратки и с правилните дати. На кой ред е грешката?

Избери реда с грешката.

Идеята

Примери вместо обяснения

Понякога отговорът не отива при клиент, а в кода. Писмата в пощата на поддръжката трябва да се разпределят по тема: доставка, връщане, плащане или друго. Програмата чака точно една от четирите думи, за да сложи писмото в правилната опашка.

Можеш да обясниш формата с думи („отговори само с категорията“). По-сигурно е да го покажеш: няколко съобщения от клиенти, всяко с отговора, който очакваш. Те стоят в историята на разговора преди истинското писмо, като предишни реплики на модела.

Това се казва примери в промпта (few-shot). Моделът продължава текста по образеца, който вижда, затова примерите държат формата по-добре от обясненията. От урока за следващия токен знаеш защо: моделът дава вероятност на продължението, а примерите правят точния формат най-вероятен.

Виж го

Три примера, четири писма

Инструкцията и разрешените категории:

SYSTEM = ("Определи темата на съобщението от клиента. "
          "Категории: доставка, връщане, плащане, друго. "
          "Отговори само с категорията.")
LABELS = ["доставка", "връщане", "плащане", "друго"]

Трите примера са двойки съобщения: клиентът (user) и отговорът, който искаме (assistant). Последното съобщение е истинското писмо:

def with_examples(message):
    return [
        {"role": "user", "content": "Пратката ми още не е дошла, а мина седмица."},
        {"role": "assistant", "content": "доставка"},
        {"role": "user", "content": "Искам да върна обувките, малки са."},
        {"role": "assistant", "content": "връщане"},
        {"role": "user", "content": "Картата ми е таксувана два пъти."},
        {"role": "assistant", "content": "плащане"},
        {"role": "user", "content": message},
    ]

Програмата приема само точна категория. Позволява малко шум: интервали, главна буква и точка накрая:

def parse_label(answer):
    label = answer.strip().lower().removesuffix(".")
    return label if label in LABELS else None

Същите четири писма без примери и с примери:

client = FakeClient()
inbox = [
    "Куриерът не ме намери на адреса.",
    "Как да върна якето, ако съм махнал етикета?",
    "Плащането с карта не минава.",
    "Имате ли магазин в Бургас?",
]
for examples in [False, True]:
    print("с примери:" if examples else "без примери:")
    parsed = 0
    for message in inbox:
        if examples:
            messages = with_examples(message)
        else:
            messages = [{"role": "user", "content": message}]
        answer = client.create(SYSTEM, messages)["text"]
        label = parse_label(answer)
        if label is not None:
            parsed += 1
        print(f'  "{answer}" → {label or "?"}')
    print(f"  разпознати: {parsed} от {len(inbox)}")

без примери:
  "Категория: доставка" → ?
  "Връщане на стока" → ?
  "Плащане." → плащане
  "Това не е от категориите, бих казал „друго“." → ?
  разпознати: 1 от 4
с примери:
  "доставка" → доставка
  "връщане" → връщане
  "плащане" → плащане
  "друго" → друго
  разпознати: 4 от 4

Без примери моделът разбира темата, но я обвива в думи и програмата разчита само „Плащане.“. С три примера отговорите са точно в нужния формат: 4 от 4.

Пробвай

Предвиди изхода

Какво печата parse_label за тези три отговора?

for answer in [" Доставка.", "Категория: доставка", "връщане"]:
    print(parse_label(answer))

Отговор

доставка
None
връщане

None
None
връщане

доставка
доставка
връщане

Пробвай

Попълни

Примерът е двойка съобщения. Каква е ролята на втория ред, отговорът, който искаме да видим?

{"role": "user", "content": "Пратката ми още не е дошла, а мина седмица."},
{"role": "", "content": "доставка"},

Идеята

Промптът е код

Една дума в промпта сменя поведението на цялото приложение, точно като ред в кода. Затова и с него се отнасяш като с код:

В кода, не в настройките. Шаблонът е функция или константа в проекта, а не текст, който някой пипа на сървъра. Така е в git: виждаш кой какво е сменил и можеш да върнеш старата версия.
Данните отделно от инструкциите. Правилата са в системния промпт, данните между тагове, а въпросът на клиента е отделно съобщение с роля user. Текстът на клиента никога не се лепи в инструкциите.
Проверка преди пускане. Смяната на промпта, която оправя един отговор, може да развали друг. Набор от въпроси с проверки, който пускаш при всяка промяна, е в урока за оценяването.
Каквото може кодът, го прави кодът. Датата на доставка, сумата и срокът за връщане се смятат в програмата и влизат готови в промпта. Моделът ги преразказва, не ги смята.

Отговорът на истински модел се мени от пускане на пускане. Затова проверките гледат правила (дължина, дата, формат), а не точни думи.

Идеята

Кога вреди

Дългият промпт се плаща всеки път. 55 токена по 10 000 въпроса на ден са 550 000 токена само за промпта. Сложи в промпта това, което този въпрос иска, а не цялото ръководство на магазина.
Много правила се бият. „Отговаряй кратко“ и „обяснявай подробно условията“ в един промпт дават случаен избор между двете. Когато правилата станат двайсет, моделът спазва част от тях.
Примерите дърпат. Ако и трите примера са за доставка, моделът по-често казва „доставка“. Примерите трябва да покриват всички случаи и да не са всички еднакви.
Промптът не е ключалка. „Никога не казвай чужди данни“ е молба, не защита. Каквото е в промпта, може да излезе навън, затова в него влиза само това, което този човек може да види. Текстът от клиента е недоверен вход; Как се пази приложение от инструкции, скрити в него, е урокът за prompt injection в модула „Агенти“.
Промптът не поправя лоши данни. Ако в базата датата е грешна, най-добрият промпт ще я повтори точно.

По-точно, за любопитните

Истинското извикване (пусни при теб). Тази програма не е в проверката на урока: трябва ти профил при доставчик на модели, ключ и пари за всяко извикване. Ключът е в променливата на средата LLM_API_KEY, никога в кода. Защо, е в урока за тайните извън кода. Доставчиците имат официални SDK-та за Java, C#, Python и JavaScript със същата форма (съобщения, роли, токени, инструменти); точните имена на класовете и методите са в документацията на доставчика. Ето заявката като JSON, с общите имена на полетата и заместител на името на модела:

{
  "model": "<името на модела>",
  "max_tokens": 1024,
  "system": "Ти си асистент на поддръжката на магазина.\nОтговаряй на „Вие“, с най-много две изречения.\nПолзвай само данните между <order> и </order>.\nАко данните не стигат, предай на колега.\nНе обещавай срокове извън данните.\n\n<order>\nномер: 1042\nстатус: изпратена\nочаквана доставка: 03.11\n</order>",
  "messages": [
    {
      "role": "user",
      "content": "Кога ще пристигне поръчка 1042?"
    }
  ]
}

Примерен отговор: блоковете в content, stop_reason и токените в usage:

{
  "content": [
    {
      "type": "text",
      "text": "Поръчка 1042 е изпратена и се очаква да пристигне на 03.11."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 62, "output_tokens": 15}
}

Без SDK заявката се праща със стандартния HTTP клиент на езика. Адресът е заместител:

# request_json е JSON-ът на заявката отгоре.
# Точната заглавка за ключа е в документацията на доставчика.
import os
import urllib.request

request = urllib.request.Request(
    "https://<доставчик>/messages",
    data=request_json.encode("utf-8"),
    headers={"Authorization": "Bearer " + os.environ["LLM_API_KEY"],
             "Content-Type": "application/json"},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

Разликата от урока за извикването е само в system: вместо ред текст е резултатът от шаблона.

Фалшивият клиент отвътре. Той пази формата на заявката и на отговора. Токените брои грубо: думите × 1,3, закръглено нагоре. Истинският брой зависи от токенизатора и е различен за български и английски.

# Стои на мястото на истинския модел: връща записан отговор,
# без мрежа и всеки път един и същ.
class FakeClient:
    VAGUE = "Здравейте! Благодаря, че се свързахте с нас. Обикновено доставката отнема от 2 до 5 работни дни според куриера и адреса. Поръчка 1042 най-вероятно ще пристигне до петък. Ако имате още въпроси, с удоволствие ще помогна!"
    VERBOSE = {
        "доставка": "Категория: доставка",
        "връщане": "Връщане на стока",
        "плащане": "Плащане.",
        "друго": "Това не е от категориите, бих казал „друго“.",
    }

    def create(self, system, messages):
        text = self._answer(system, messages)
        input_tokens = tokens(system) + sum(tokens(m["content"]) for m in messages)
        return {"text": text, "stop_reason": "end_turn",
                "input_tokens": input_tokens, "output_tokens": tokens(text)}

    def _answer(self, system, messages):
        last = messages[-1]["content"]
        if "Категории:" in system:
            label = label_of(last)
            return label if len(messages) > 1 else self.VERBOSE[label]
        eta = field(system, "очаквана доставка: ")
        if eta is None:
            return self.VAGUE
        number = field(system, "номер: ")
        status = field(system, "статус: ")
        return f"Поръчка {number} е {status} и се очаква да пристигне на {eta}."


# Грубо: думите × 1,3, закръглено нагоре.
def tokens(text):
    return (len(text.split()) * 13 + 9) // 10


def label_of(message):
    m = message.lower()
    if "куриер" in m or "пратка" in m:
        return "доставка"
    if "върна" in m:
        return "връщане"
    if "карта" in m or "плащане" in m:
        return "плащане"
    return "друго"


def field(system, name):
    for line in system.split("\n"):
        if line.startswith(name):
            return line[len(name):]
    return None

Защо тагове. <order> и </order> не са специален синтаксис. Моделът е виждал много текст с такива тагове и разбира къде започва и къде свършва блокът. Със същия успех работят ### или кавички, стига да са едни и същи навсякъде.

„Мисли стъпка по стъпка“. За задачи с няколко стъпки (сметка, сравнение) помага моделът първо да напише разсъжденията си и после отговора. Това струва още токени и време, а отговорът трябва да се отдели от разсъжденията, преди да стигне до програмата. Структурираният изход от следващия урок прави това отделяне надеждно.

f-низът с три кавички пази всичко буквално, включително отстъпа. Затова редовете на шаблона са без отстъп, макар да са във функция. textwrap.dedent е другият начин.

Упражнение

Шаблон за връщане

Реши задачата в редактора си.

Напиши шаблон return_prompt(order) за въпросите за връщане. Поръчката има номер, дата на доставка (или няма, ако още не е доставена) и сума в евро. Шаблонът има три правила и данните между <order> и </order>. Ако датата я няма, в данните пише „още не е доставена“: кодът решава какво да каже, а не моделът. Пусни го за двете поръчки и отпечатай --- след всеки промпт.

Ти си асистент на поддръжката на онлайн магазин.
Клиентът може да върне поръчката до 14 дни след доставката.
Ползвай само данните между <order> и </order>.

<order>
номер: 1187
доставена на: 21.10
сума: 89.90 €
</order>
---
Ти си асистент на поддръжката на онлайн магазин.
Клиентът може да върне поръчката до 14 дни след доставката.
Ползвай само данните между <order> и </order>.

<order>
номер: 1203
доставена на: още не е доставена
сума: 34.50 €
</order>
---

Още задачи

Срокът в кода. Добави в данните ред „може да се върне до:“ с датата 14 дни след доставката, сметната в програмата.
Още една проверка. Добави в check правило „без обещание за ден от седмицата“: отговорът не съдържа „понеделник“, „вторник“ и т.н. до „неделя“. Колко проверки минава тогава неясният отговор?

Тест

Провери се

1. Асистентът обещава „до петък“, а в базата датата е 03.11. Коя поправка е правилната?Програмата слага данните на поръчката в промпта и правило „ползвай само данните“Въпросът се праща още веднъж, докато отговорът стане веренВ промпта се добавя „не лъжи“

2. Програмата чака една от четирите категории, а моделът връща „Категория: доставка“. Какво помага най-много?Няколко примера с въпрос и отговор точно в нужния форматПо-дълго обяснение какво е категорияДа се приеме всеки отговор, в който се среща думата „доставка“

3. Шаблонът слага в промпта поръчките на всички клиенти, за да е „по-пълен“. Какъв е проблемът?Никакъв: моделът сам ще избере правилната поръчкаСамо цената: промптът става по-дълъгМоделът може да каже на един клиент данни за чужда поръчка

4. Защо промптът се пази в кода, а не се пише на ръка в настройките на сървъра?Защото така е по-кратъкЗащото моделът чете само промпти от кодаТака е в git, минава преглед и тестове, и всяка промяна може да се върне

Промптът е код

Бисквитки