Модельдің chat template-ін салмақтарымен бірге нұсқалау керек

Модель ауысқаннан кейінгі бос жауап LLM-нің «мінезіне» ғана байланысты болмайды. Көбіне команда сол салмақтарды жүктеп, сол inference server-ді іске қосады, бірақ модельге байқамай басқа токендер тізбегін береді. Себеп chat template ішінде болуы мүмкін: Jinja файлында, токенизатор баптауында немесе рөлдерді өз API-іне бейімдеген аралық қабатта.

Модельдің chat template-ін салмақтар мен токенизатор сияқты жеткізу құрамының бір бөлігі деп қараңыз. Оның нұсқасын бекітіп, регрессиялық тест жүргізбесеңіз, қолыңызда қайталанатын модель болмайды. Кейде жауап беретін, кейде бос жол қайтаратын, кейде tool calling-ті жай ғана сәндік JSON-ға айналдыратын артефактілер жиынтығы ғана қалады.

Hugging Face мұны қарапайым түсіндіреді: чат моделі токендердің сызықтық тізбегін жалғастырады, ал рөлдер мен хабарлама шекараларын шаблон қосады. Бір базалық модельден дообучение өткен екі модель мүлде басқа басқару токендерін күтуі мүмкін. Осы токендердегі қате салмақтар өзгермесе де, модельдің жұмысын нашарлатады.

Чат шаблоны модель контрактына кіреді

Модель контракты конфигурациядағы бір атаудан тұрмайды. Оған салмақтар, tokenizer, special tokens, chat template, генерация параметрлері және жауапты талдау ережелері кіреді. Команда тек model_id жаңартқанда, контракттың жартысын байқамай өзгертіп жіберуі мүмкін.

Бұл open-weight модельдерде анық көрінеді. Бір формат хабарламаларды \u003c|role|\u003e сияқты тегтермен бөледі, екіншісі нұсқаулық маркерлерінің жұбын қолданады, үшіншісі reasoning үшін қызметтік арна қосады, төртіншісі құрал сипаттамасын XML тәрізді арнайы разметкамен шығарады. Адам үшін бәрі «диалог» болып көрінеді. Модель үшін бұлар келесі токенді болжауға үйретілген әртүрлі префикстер.

Командалар жиі араластыратын маңызды айырмашылық бар: хабарламаның API схемасы мен оқыту форматы бір нәрсе емес. API схемасы бірдей көрінуі мүмкін:

{
  "role": "user",
  "content": "Найди статус заявки 4815"
}

Бірақ рендерленгеннен кейін бір модель мына жолды көреді:

\u003c|user|\u003e
Найди статус заявки 4815\u003c|end|\u003e
\u003c|assistant|\u003e

Ал екіншісі мынадай жолды көреді:

\u003cs\u003e[INST] Найди статус заявки 4815 [/INST]

Екінші нұсқаны бірінші JSON-нан шығару мүмкін емес. Оны модель артефактілерінен немесе авторы оқыту кезінде қолданған форматтан алу керек.

Практикалық ереже қарапайым: release manifest-ке салмақтар ревизиясымен бірге шаблон хэшін де жазыңыз. Шаблон tokenizer config ішінде сақталса, токенизатор файлдарының бүкіл жиынын хэштеңіз. Inference server шаблонды flag немесе бөлек жол арқылы алса, wiki-дегі атауды емес, нақты берілген файлды бекітіңіз.

model:
  repository: org/model-instruct
  revision: 8f31c2a
  tokenizer_sha256: "..."
  chat_template_sha256: "..."
serving:
  runtime: vllm
  runtime_version: "..."
  add_generation_prompt: true
  temperature: 0

Бұл manifest өздігінен жауаптарды жақсартпайды. Бірақ инцидентті зерттеуге мүмкіндік береді. Екі аптадан кейін prompt-қа нақты не түскенін қалпына келтіре аласыз, шаблонда бірдеңе өзгерді ме деп дауласпайсыз.

Бос жол көбіне бір артық токеннен басталады

Бос жауаптың себептері көп: сервер сүзгісі, тым аз шығару лимиті, stop sequence немесе parser қатесі. Дегенмен форматтауды алғашқылардың бірі болып тексеру керек, өйткені ол модельді бірден EOS-токеніне немесе жабық қызметтік блокқа жеткізуі мүмкін.

Жиі кездесетін ақау былай көрінеді. Адаптер тарихты рендерлеп, assistant маркерін қолмен қосады. Ал шаблон add_generation_prompt=true кезінде оны әлдеқашан қосып қойған. Prompt ішінде assistant-тің екі бастау белгісі қатар пайда болады. Бір модель рөлді қайталай бастайды, екіншісі EOS таңдайды, үшіншісі сервер кейін «жарамсыз assistant жауабы» деп алып тастайтын мәтін шығарады.

Кері қате де жиі кездеседі. Команда add_generation_prompt параметрін «соңғы хабарлама бәрібір user-дікі» деп өшіреді. Нақты модель үшін бұл кірістің пайдаланушы блогының ішінде аяқталатынын білдіреді. Ол user мәтінін адал түрде жалғастырады, assistant жауабын бастамайды.

Мұны temperature арқылы емдеуге тырыспаңыз. Temperature келесі токенді таңдауға әсер етеді, бірақ модельге қазір кімнің кезегі екенін түсіндірмейді. Алдымен токенизацияға дейінгі нақты жолды және оның соңындағы token IDs тізімін сақтаңыз.

from transformers import AutoTokenizer

model_id = "org/model-instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
messages = [
    {"role": "system", "content": "Отвечай кратко."},
    {"role": "user", "content": "Сколько будет 19 * 3?"},
]

rendered = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
ids = tokenizer.encode(rendered, add_special_tokens=False)

print(repr(rendered[-240:]))
print(ids[-40:])
print(tokenizer.convert_ids_to_tokens(ids[-40:]))

Дұрыс зерттеу кезінде бұл команда тексеруге болатын үш артефакт береді: жолдың соңғы бөлігі, токен идентификаторлары және олардың мәтіндік көрінісі. Оларды алдыңғы релиз эталонымен салыстырыңыз. Тек модельдің соңғы жауабын салыстырмаңыз, ол қате қай жерде пайда болғанын тым кеш көрсетеді.

Тағы бір қауіп special tokens-ті қайта қосуға байланысты. Transformers құжаттамасы генерацияға дайындау кезінде apply_chat_template(..., tokenize=True) қолдануды ұсынады, өйткені рендерлеу мен токенизацияны бөлек орындағанда қызметтік токендерді тағы бір рет қосу оңай. Код жолмен жұмыс істеуге мәжбүр болса, токенизаторда add_special_tokens=False параметрін ашық көрсетіп, оны тестпен бекітіңіз.

Әр модельдің нақты ережесінсіз рөлдерді «қалыпқа» келтіруге болмайды

Хабарламалардың бірыңғай ішкі форматы пайдалы. Бірақ әр модельге арналған адаптерсіз рөлдердің бірыңғай семантикасы қауіпті. Ең жағымсыз қателер платформа тарихты үнсіз «жөндегенде» пайда болады.

Мысалы, өнім бірнеше system хабарламасына рұқсат береді: біреуі қолданбадан, екіншісі әкімшіден, үшіншісі тапсырма конфигурациясы арқылы пайдаланушыдан келеді. Модель басында тек бір system-turn қабылдауы мүмкін. Адаптер оларды бөлгішсіз біріктірсе, нұсқаулар шекарасы жоғалады. Екінші system хабарламасын user-ге ауыстырса, оның басымдығын өзгертеді. Ал үнсіз алып тастаса, audit log-та жазылғаны мен модель көргені екі бөлек болады.

Әр модель үшін саясат анық жазылуы керек:

• рөлдер тізбегін өзгертпей қабылдау;
• рұқсат етілген system хабарламаларын алдын ала бекітілген ереже бойынша біріктіру;
• қолдау көрсетілмейтін тарихты түсінікті қате арқылы қабылдамау;
• модель tool use үшін бөлек тармақ берсе, жеке шаблон қолдану;
• соңғы turn assistant генерациясын шынымен дайындап тұрғанын тексеру.

Соңғы тармақ ойлағаннан маңызды. JSON ішіндегі assistant рөлі әрқашан «модель жалғастыруы керек» дегенді білдірмейді. Кейде соңғы assistant-turn prefill болады: жауап жолын бастап қойып, модельден оны жалғастыруды сұрайсыз. Бұл басқа режим. Transformers-та ол үшін continue_final_message бар. Оны add_generation_prompt параметрімен бірге қолдануға болмайды: бір режим жаңа жауап ашады, екіншісі ағымдағы жауапты жалғастырады.

Мұндай тест GPU іске қосылмай тұрып құлауы керек:

def validate_history(messages: list[dict]) -> None:
    allowed = {"system", "user", "assistant", "tool"}
    for index, message in enumerate(messages):
        if message.get("role") not in allowed:
            raise ValueError(f"messages[{index}].role is unsupported")
        if message["role"] == "tool" and not message.get("content"):
            raise ValueError(f"messages[{index}] has an empty tool result")

    if messages and messages[0]["role"] == "tool":
        raise ValueError("tool result cannot start a conversation")

Бұл барлық модельге ортақ валидатор емес. Оның артықшылығы да осында: «үйлесімді API»-ге үміт артпай, өз ережелеріңізді қай жерде жазу керегін көрсетеді.

Thinking blocks үшін бөлек тест жиыны керек

Reasoning модельдері жалған сенімділіктің тағы бір көзін қосты. Команда reasoning_content, thinking өрістерін немесе \u003cthink\u003e тәрізді блоктарды көріп, бір форматты барлық модельге бере бастайды. Содан кей жауаптар үзіледі, жасырын reasoning пайдаланушыға түседі, ал құрал шақыруларының бір бөлігі жабық блоктың ішінде қалады.

Thinking block кәдімгі assistant мәтініне тең емес. Шаблон оны генерация алдында ашып, көрінетін жауап алдында жабуы немесе соңғы хабарламада бөлек өріс күтуі мүмкін. Transformers құжаттамасы ескертетіндей, prefill-ді content ішіне салсаңыз, шаблон генерация басталмай тұрып reasoning block-ты жауып қоюы мүмкін. Reasoning-ті жалғастыру үшін шаблонның өзі сілтеме жасайтын reasoning өрісін толтырыңыз.

Мұнда екі міндеттің шекарасын нақты ажырату қажет:

1. Модель өз форматының ішінде reasoning жасайды, ал қолданба тек соңғы жауапты сақтайды.
2. Қолданба басталып қойған reasoning-ті жалғастырады немесе көп қадамды trace-ті қайта шығарады.

Бірінші жағдайда модель мен өнім мұны талап етпесе, ішкі блокты тарихқа қайта бермеңіз. Бұл prompt-ты үлкейтеді, пайдаланушыға қажет емес ақпаратты ашады және бас тарту нүктелерін көбейтеді.

Екінші жағдайда бөлек тест матрицасын жасаңыз. Қарапайым диалогтар оның орнын баспайды. Кемінде мына жағдайларды тексеріңіз: бос reasoning, content-і бос reasoning prefill, соңғы жауап алдындағы аяқталған reasoning, reasoning-тен кейінгі tool call, tool result қайтару және келесі assistant-turn.

Пайдалы контрактілік тест мәтіннің әдемілігін емес, рендерлеу құрылымын тексереді:

def test_reasoning_prefill_keeps_block_open(tokenizer):
    messages = [
        {"role": "user", "content": "Объясни 1 + 1"},
        {
            "role": "assistant",
            "reasoning_content": "Нужно сложить два числа. ",
            "content": "",
        },
    ]

    prompt = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        continue_final_message="reasoning_content",
    )

    assert prompt.endswith("Нужно сложить два числа. ")
    assert "\u003cthink_end\u003e" not in prompt[-80:]

Мұндағы нақты токендер шартты, ал қағиданы тексеру шартты емес: тест prompt-тың соңғы таңбасында қызметтік блоктың қандай күйде болуы керегін білуі тиіс. Модельдің нақты шекараларын қойыңыз. Егер шаблон reasoning өрістерін қолданбаса, тест бейімделіп кетпей, конфигурация қатесімен аяқталуы керек.

Tool calling үш протокол түйіскен жерде бұзылады

Tool calling кемінде үш түрлі форматты қамтиды: қолданба құралды қалай сипаттайды, шаблон бұл сипаттаманы модельге қалай көрсетеді және сервер жасалған шақыруды API объектісіне қалай талдайды. Команда көбіне тек соңғы қабатты тексереді. Модель JSON қайтарды, демек «құралдар жұмыс істейді» деп ойлайды. Бұл тек бір мысалдың parser арқылы өткенін көрсетеді.

Шаблон JSON Schema-ны Python тәрізді сигнатураға, XML тегтеріне немесе өзіндік блокқа айналдыруы мүмкін. Бір шақыру немесе тізім шығара алады. Tool result tool рөлімен, функция атауымен, шақыру идентификаторымен немесе тек мәтіндік content арқылы келуін талап етуі мүмкін. Hugging Face tool_calls-ті assistant хабарламасындағы тізім ретінде сипаттайды және нәтиже үшін tool рөлін бөлек көрсетеді. Бірақ разметка мен special tokens модельге байланысты екенін, олардың оқыту форматына сәйкес келуі керегін атап өтеді.

Мына ең қысқа диалог регрессияда міндетті түрде болуы тиіс:

messages = [
    {"role": "user", "content": "Какая погода в Алматы?"},
    {
        "role": "assistant",
        "tool_calls": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "arguments": {"city": "Алматы"},
                },
            }
        ],
    },
    {
        "role": "tool",
        "name": "get_weather",
        "content": "{\"temperature_c\": 18, \"condition\": \"ясно\"}",
    },
]

Бұл сценарийде бес нәрсені тексеріңіз.

• Шаблон tools берілгенде модель күтетін режимде get_weather сипаттамасын шығарады.
• Assistant tool call ішінде дәл get_weather атауы бар, ал city аргументі артық экранирлеуі бар жолға айналмайды.
• Tool result дұрыс рөл мен блок шекараларын алады.
• Tool result-тен кейін шаблон жаңа assistant жауабының басталуын қосады.
• Модель кәдімгі жауап беруі керек болса, құралдың JSON-ы пайдаланушыға арналған соңғы мәтінде көрінбейді.

«Кез келген модельді қатаң OpenAI function calling шығаруға system prompt арқылы мәжбүрлейік» деген ұсыныс жиі айтылады. Ол демо үшін тез нәтиже береді. Бірақ production ортада ұзақ тарихта, бірнеше құралда және модель жаңарғанда сәтсіздікке ұшырайды. System prompt токендерді, форматты және модель құрал шақыруға үйренген мысалдарды алмастыра алмайды.

Көп адам өткізіп алатын тағы бір тест бар: бір turn ішіндегі бірнеше шақыру. Таңдалған модель әдетте бір құрал шақырса да, контракт мінез-құлықты анықтауы керек. Орындаушы массивті қолдап, рұқсат етілген шақыруларды берілген ретпен орындайды немесе валидатор екінші шақыруды қабылдамайды. Біріншісін үнсіз алу әрекетті жоғалтады және қате туралы жазба қалдырмайды.

Snapshot prompt «жауап қалыпты көрінеді» деген бағадан пайдалырақ

Мінез-құлық бағалары қажет, бірақ олар шаблондағы ақаудың орнын нашар көрсетеді. Бір prompt temperature 0.7 кезінде кездейсоқ жақсы, ал 0.0 кезінде нашар жауап беруі мүмкін. Рендерлеу snapshot-ы себепті генерациядан бұрын көрсетеді.

Қолдайтын әр модельдер отбасы үшін fixtures каталогын жасаңыз. Оның ішінде кіріс хабарламалары мен рендерлеудің эталон нәтижелері болсын. Нақты клиент мәтінін, қолжетімділік токендерін немесе ішкі жүйелер жауаптарын сақтамаңыз. Шекараларды көрінетін ететін қысқа синтетикалық фразаларды пайдаланыңыз.

fixtures/
  normal_chat.json
  normal_chat.prompt.txt
  system_and_user.json
  system_and_user.prompt.txt
  tool_roundtrip.json
  tool_roundtrip.prompt.txt
  reasoning_prefill.json
  reasoning_prefill.prompt.txt

Snapshot жалғыз эталон болмауы керек. Қате мәнін түсіндіретін инварианттарды қосыңыз. Мысалы, кәдімгі сұрауда prompt assistant басталуының маркерімен аяқталуы керек. Tool roundtrip кезінде tool result-тен кейін дәл бір сондай маркер шығуы тиіс. Assistant-prefill тарихына жаңа assistant header қосылмайды. Tools жоқ кірісте алдыңғы тесттен қалған функция сипаттамасы болмауы керек, әйтпесе сұраулар арасында күй ағып кетеді.

assert rendered.count(assistant_start) == 1
assert rendered.endswith(assistant_start)
assert tool_schema_marker not in rendered_without_tools
assert tokenizer.eos_token_id not in input_ids[:-1]

Соңғы тексеріс модель форматына байланысты: кей шаблондар хабарламалар арасында EOS-ті заңды түрде қолданады. Бұл assert-ті сол күйінде көшірмеңіз. EOS қай жерде рұқсат етілетінін және оның нені білдіретінін ескеріп, өз инвариантыңызды жазыңыз. Инженердің жұмысы дегеніміз жасырын білімді тексерілетін ережеге айналдыру.

Токенизация тесті жолдан көрінбейтін қателерді ұстайды

Екі prompt журналда бірдей көрініп, әртүрлі токенизациялануы мүмкін. Себеп қосылған BOS, көрінбейтін бос орын, Unicode қалыпқа келтіру айырмасы немесе токенизатордың екінші шақырылымы special tokens-ті автоматты түрде қосуы болуы ықтимал.

Сондықтан бірнеше қысқа fixture үшін rendered text-пен бірге token IDs-тің күтілетін соңғы бөлігін де сақтаңыз. Бүкіл массивті бекіту міндетті емес, өйткені мәтін дұрыс өзгертілгенде ол да өзгеруі мүмкін. Рөл шекаралары мен соңғы қызметтік токендерді бекіту жеткілікті.

def test_generation_suffix(tokenizer):
    messages = [{"role": "user", "content": "ping"}]
    ids = tokenizer.apply_chat_template(
        messages,
        tokenize=True,
        add_generation_prompt=True,
    )

    tail = ids[-6:]
    assert tail == [151644, 8948, 198, 151645, 198, 151646]

Мысалдағы сандар әмбебап емес. Репозиторийіңізде олар таңдалған токенизатордың нақты IDs мәндері болуы керек. Команда оларды «оқу қиын» деп сақтаудан қорықса, шаблон мен токенизатордың сәйкестігін көрсететін ең жақсы сигналдан бас тартады.

Unicode-ті бөлек тексеріңіз. Қазақстан өнімдері бір хабарламада орыс тілін, кириллдегі қазақ тілін, латын графикасындағы қазақ тілін, ағылшын тілін және аралас мәтінді қабылдауы мүмкін. Рөлдерді біріктіргенде шаблон пайдаланушы мазмұнын өзгертпеуі керек. І, ң, ғ, апострофтар, жол ауыстырулар және tool result ішіндегі JSON жолы бар fixture жүргізіңіз. Бұл аударма сапасының тесті емес. Бұл аралық қабаттың токенизацияға дейін байттарды бұзбайтынын тексеру.

Тест матрицасы «функциялар» бойынша емес, ауысулар бойынша құрылуы керек

Нашар тест жиыны мүмкіндік атауларымен құрылады: «чат тесті бар», «tools тесті бар», «reasoning тесті бар». Мұндай жиын assistant → tool → assistant ауысуы бұзылған болса да өтуі мүмкін. Форматтау көршілес хабарламаларға тәуелді, сондықтан рөлдер мен режимдер арасындағы ауысуларды тексеру керек.

Reasoning жоқ модель үшін ең аз матрица мыналарды қамтиды: system → user → assistant generation, user → assistant-prefill, user → assistant tool call, assistant tool call → tool result → assistant generation және өнім модельге жүгінгенге дейін бірнеше user-turn қабылдаса, қатар келген бірнеше user-turn.

Reasoning моделі үшін thinking block ішіндегі және оның айналасындағы ауысуларды қосыңыз. Мультимодаль модель үшін шаблон қабылдайтын content block-тердің әр түрін тексеріңіз. Автоматты tool choice бар серверде parser модель шығаратын дәл форматты түсінетінін тексеріңіз. vLLM және ұқсас runtime-дар chat template таңдауын tool-call parser таңдауынан бөледі. Бұл екі бөліктің үйлесімділігін автоматты деп санауға болмайды.

Мен бір модельге жүз емес, он fixture-тен бастар едім. Бесеуі негізгі рөлдерге, үшеуі құралдарға, екеуі reasoning немесе prefill-ге арналған болсын. Біреуі инцидентті анықтағанда, ең аз қайталанатын fixture қосып, тапсырманы онсыз жабуға тыйым салыңыз. Сонда жиын қамту туралы қиялдан емес, нақты ақаулардан өседі.

Модельді жаңарту үйлесімділікке сенуді емес, canary-ді талап етеді

OpenAI-мен үйлесімді endpoint ыңғайлы, өйткені клиент бүкіл кодты емес, тек base URL-ді өзгертеді. Бірақ тасымал үйлесімділігі chat template үйлесімділігін білдірмейді. Екі сервер бір messages payload-ын қабылдап, әр модельге әртүрлі prompt құрауы мүмкін. Платформа мұны ашық әрі тексерілетін түрде жасаса, бұл қалыпты.

Жаңартудан бұрын fixture-ді ескі және жаңа артефактта жүргізіңіз. Алдымен рендерлеуді, содан кейін token IDs-ті, одан соң tool calling құрылымдық нәтижесін, ең соңында ғана еркін жауап сапасын салыстырыңыз. Шаблон әдейі өзгерсе, review snapshot-тағы әр айырмашылықтың себебін қамтуы керек. «Модель репозиторийіндегі жаңа шаблон» себеп емес, өзгерістің көзі ғана.

AI Router ішінде командалар бір OpenAI-мен үйлесімді клиентті сақтай алады. Бірақ production маршруты үшін әр модельдер отбасына жеке контракт профилін ұстаған жөн: рөлдер форматы, құралдар режимі, thinking өрістері, parser және тексерулер матрицасы. Бұл маршрутизация модельді бағаға, кідіріске немесе деректерді орналастыру талаптарына қарай ауыстырғанда әсіресе пайдалы.

Модельді жалпы трафикке шығармаңыз, қолданбадағы әр маңызды ауысу үшін кіріске нақты қандай жол түсетінін білмей тұрып. Команда бұл жолды көрсете алмаса, модельмен сөйлесуді есту арқылы тексеріп отыр. Production үшін бұл жеткіліксіз.