# Parsing Respons

Semakin umum model chat menghasilkan output terstruktur, bukan sekadar satu string balasan. Misalnya, [model penalaran](https://huggingface.co/reasoning-course) dapat mengeluarkan rantai pemikiran yang berisi jejak penalarannya, sementara model [tool calling](./chat_extras) dapat mengeluarkan nama fungsi dan argumennya.

Masalah dengan output terstruktur adalah bahwa output LLM pada dasarnya tidak terstruktur. API LLM biasanya menerima dan mengembalikan dict pesan, dengan kunci seperti `role` dan `content` serta `reasoning_content`, tetapi secara internal, LLM sebenarnya hanya melanjutkan satu rangkaian token. Kami menggunakan lapisan penghubung untuk menghubungkan API yang berhadapan dengan pengguna ke aliran token aktual dari model. Untuk mengubah input menjadi aliran token, kami menggunakan [`chat_templates`](./chat_templating), yang dibahas dalam dokumen lain. Dokumen ini membahas bagian lain dari lapisan penghubung tersebut: **Response templates**, yaitu sistem untuk mengubah kembali token yang dihasilkan oleh model menjadi dict respons terstruktur.

Dalam banyak hal, response templates melakukan operasi kebalikan dari chat templates. Dengan chat templates, Anda memasukkan daftar pesan, dan Anda mendapatkan token yang siap diinput ke model. Dengan response templates, Anda memasukkan token output mentah dari model, dan Anda mendapatkan pesan terstruktur. Seperti chat templates, response templates memungkinkan pengguna untuk mengabaikan detail rumit mengenai format spesifik dan token kontrol yang diharapkan oleh model, serta menggunakan API universal berupa dict pesan yang berfungsi dengan model apa pun.

Cara terbaik untuk memahami template respons adalah dengan melihatnya dalam praktik. Titik masuk utama adalah metode [parse_response()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.parse_response), yang menerima satu urutan atau batch:

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

checkpoint = "HuggingFaceTB/SmolLM3-3B"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
model = AutoModelForCausalLM.from_pretrained(checkpoint, dtype="auto", device_map="auto")

messages = [{"role": "user", "content": "Summarize the end of the Cold War, very briefly."}]
input_ids = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt")["input_ids"].to(model.device)
outputs = model.generate(input_ids, max_new_tokens=1024)[0, input_ids.shape[1]:]
out_text = tokenizer.decode(outputs)
print(tokenizer.parse_response(out_text, prefix=input_ids[0]))
# Outputs a structured dict: {"role": "assistant", "reasoning_content": "...", "content": "..."}
```

Ketika sebuah tokenizer memiliki `response_template`, metode `parse_response` akan mengubah pesan keluaran menjadi dict terstruktur dengan rapi, siap untuk ditambahkan ke percakapan. Perhatikan bahwa kita juga perlu meneruskan `prefix` (token prompt) ke metode ini. Hal ini karena banyak template percakapan memulai pesan atau membuka blok berpikir sebelum membiarkan model memulai responsnya, sehingga parser kita perlu melihat prompt untuk memahami pesan tersebut. Seluruh prefix sebelum giliran terakhir dibuang; kita hanya mem-parsing satu pesan pada satu waktu. Kita hanya membutuhkan prefix untuk memastikan kita melihat pesan terakhir secara utuh, dan tidak melewatkan bidang apa pun yang sudah terisi sebelumnya!

Karena prefix yang hilang dapat menyebabkan pesan yang sudah diisi sebelumnya (prefilled) salah diinterpretasikan secara diam-diam, `prefix` bersifat wajib. Mengabaikannya akan memicu error. Dalam kasus langka di mana Anda yakin bahwa hasil generasi sudah berisi pesan lengkap dan tidak memerlukan konteks prefix, Anda dapat meneruskan `prefix=""` (atau daftar kosong dari token id) untuk secara eksplisit memilih untuk tidak menggunakannya.

Jika tokenizer tidak memiliki template respons yang disetel, `parse_response` akan memicu error. Kami sedang berupaya menambahkan template ke lebih banyak model secepat mungkin!

## Parsing respons streaming

Pada contoh di atas, kami mem-parsing respons model sekaligus setelah proses generasi selesai. Namun, sering kali kami ingin mem-parsing pesan parsial saat pesan tersebut sedang dihasilkan, terutama pada aplikasi yang berhadapan langsung dengan pengguna, di mana kami tidak hanya ingin menampilkan halaman statis selama satu atau dua menit hingga model selesai.

Jika Anda ingin parsing streaming, panggil `tokenizer.get_response_parser()`, yang mengembalikan sebuah `ResponseParser`. Sama seperti `parse_response`, berikan prompt chat sebagai `prefix=` agar parser mengetahui bagian pesan mana saja yang telah diisi sebelumnya oleh template chat. Objek yang dikembalikan adalah parser berstatus (stateful) yang dapat Anda beri teks saat model menghasilkannya:

```python
parser = tokenizer.get_response_parser(prefix=input_ids[0])
for event in parser.initial_events:
    render(event)  # Display the partial message to the user however you want to
for chunk in model_output:
    for event in parser.feed(chunk):
        render(event)
message, final_events = parser.finalize()
for event in final_events:
    render(event)
```

Jika permintaan mencakup tools, teruskan juga (`get_response_parser(..., tools=tools)`). Argumen tool-call kemudian di-tipe dari JSON Schema tool pemanggil saat setiap region ditutup, sehingga konsumen streaming melihat argumen yang di-tipe sesuai schema pada `region_close` alih-alih hanya setelah `finalize()`. Lihat [Typing tool-call arguments](#typing-tool-call-arguments) untuk detailnya.

Parser akan mengeluarkan **event** saat teks dari proses generasi dimasukkan. Hal ini menunjukkan region mana yang sedang digenerasi. Ketika region selesai, region tersebut akan dikeluarkan dalam event terpisah dengan konten yang telah di-parse secara lengkap. Pada akhir generasi, metode `finalize()` akan mem-flush teks yang tersisa dan mengeluarkan event akhir, serta dict pesan lengkap.

Perlu dicatat bahwa meskipun `parse_response` dapat menerima batch, parsing yang di-stream selalu bersifat single-sequence: setiap `ResponseParser` melacak status dari satu generasi. Jika Anda ingin melakukan streaming beberapa generasi sekaligus, buat satu `ResponseParser` untuk setiap sequence.

## Peristiwa streaming

Setiap event parsing yang di-stream adalah dict dengan kunci `type`. Ada tiga jenis:

| Tipe           | Deskripsi                                                                         | Isi                                                                                                                        |
|----------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `region_open`  | Menunjukkan bahwa model telah memulai region baru, seperti `content` atau `reasoning_content`. | `field` (str): nama field.                                                                                                  |
| `region_chunk` | Sebagian teks untuk wilayah saat ini.                                             | `field` (str): nama field. `text` (str): chunk baru. `dirty` (bool): `True` jika chunk adalah teks mentah yang perlu di-parse. |
| `region_close` | Menunjukkan bahwa sebuah region telah selesai, dan kunci tersebut kini telah difinalisasi.                | `field` (str): nama field. `value` (any): nilai yang sepenuhnya di-parse untuk region                                             |

Event `region_chunk` dipancarkan untuk setiap region saat byte diterima, sehingga UI streaming dapat menampilkan progres bahkan untuk region terstruktur. Untuk region yang menyerupai teks (`text`, `int`, `float`, `bool`), chunk diberi flag `dirty=False`: setiap chunk sudah merupakan bagian dari nilai akhir (di luar spasi di akhir yang dihapus saat penutupan). Untuk region terstruktur, seperti tool call dalam format JSON, chunk diberi flag `dirty=True`. Ini berarti teks adalah badan mentah yang belum di-parse; aman untuk ditampilkan secara bertahap, tetapi nilai *parsed* (dict, list, dll.) baru tiba pada event `region_close` yang sesuai. Dalam kedua kasus, nilai akhir dari sebuah region selalu dibawa oleh `region_close`, sehingga konsumen yang tidak peduli dengan rendering antara dapat mengabaikan event `region_chunk`.

Jika `prefix` chat menulis sesuatu ke dalam pesan (misalnya, template membuka blok berpikir, atau prefill asisten memulai respons sebelum diserahkan ke model), parser mengekspos event-event tersebut sebagai `parser.initial_events`, yaitu daftar yang dapat Anda putar ulang ke renderer Anda sebelum memberikan keluaran model apa pun. Wilayah yang dibuka *dan* ditutup di dalam prefix menghasilkan urutan lengkap `region_open` / `region_chunk` / `region_close`, dan nilai yang diurai akan masuk ke dict keluaran, persis seolah-olah model itu sendiri yang menulisnya.

Alur peristiwa yang tipikal mungkin terlihat seperti ini:

```python
{"type": "region_open",  "field": "reasoning_content"}
{"type": "region_chunk", "field": "reasoning_content", "text": "I should ", "dirty": False}
{"type": "region_chunk", "field": "reasoning_content", "text": "greet the user", "dirty": False}
{"type": "region_close", "field": "reasoning_content", "value": "I should greet the user"}
{"type": "region_open",  "field": "tool_calls"}
{"type": "region_chunk", "field": "tool_calls", "text": '{"name": "greet_user", ', "dirty": True}
{"type": "region_chunk", "field": "tool_calls", "text": '"arguments": {"greeting": "Hi!"}}', "dirty": True}
{"type": "region_close", "field": "tool_calls", "value": {"type": "function", "function": {"name": "greet_user", "arguments": {"greeting": "Hi!"}}}}
```

Perhatikan bahwa `reasoning_content` dikirim dengan `dirty=False`, karena field seperti `reasoning_content` dan `content` biasanya hanya berupa teks mentah. Ini berarti Anda dapat memperlakukan chunk sebagai "output parsial" yang valid. Namun, `tool_calls` ditandai sebagai `dirty` karena teks mentahnya memerlukan pembersihan yang signifikan - tool call sering kali perlu di-parse sebagai JSON atau format lain, lalu disusun ulang untuk menghasilkan dict tool call final. Akibatnya, output final untuk region-region ini sering kali terlihat sangat berbeda dari teks mentahnya. Parsing final ini hanya akan terjadi ketika `region_close` tercapai. Terserah Anda apa yang ingin dilakukan dengan chunk `dirty` sampai saat itu - Anda dapat menampilkannya apa adanya untuk menunjukkan output "mentah" kepada pengguna, atau Anda dapat menunggu sampai ada sesuatu yang bersih untuk ditampilkan.

Bagian ini merangkum sebagian besar hal yang perlu Anda ketahui untuk menggunakan response templates. Sisa dokumen ini berfokus pada bagian internal dari sistem parsing dan cara menulis response templates. Hal ini terutama relevan bagi developer dan penulis model. Sebagian besar orang dapat dengan aman berhenti di sini!

## Lanjutan: Menulis template respons

Cara terbaik untuk memahami cara menulis template respons adalah dengan memilih contoh konkret. Berikut adalah contoh tampilan balasan mentah dari `SmolLM`:

```txt
<think>
I should greet the user
</think>

<tool_call>{"name": "greet_user", "arguments": {"greeting": "Hi!"}}</tool_call>
```

Ketika kami mengurai output ini dalam format dict pesan standar, seharusnya terlihat seperti ini:

```json
{
    "role": "assistant",
    "reasoning_content": "I should greet the user",
    "tool_calls": [
        {"type": "function", "function": {"name": "greet_user", "arguments": {"greeting": "Hi!"}}}
    ]
}
```

Dan berikut adalah template yang mem-parsenya. Jangan merasa gentar — sebagian besar isinya cukup mudah dipahami!

```python
{
    "defaults": {"role": "assistant"},
    "start_anchor": "<|im_start|>assistant\n",
    "fields": {
        "reasoning_content": {"open": "<think>", "close": "</think>", "content": "text"},
        "tool_calls": {
            "open": "<tool_call>",
            "close": "</tool_call>",
            "repeats": True,
            "content": "json",
            "transform": {"type": "function", "function": "{content}"},
        },
        "content": {
            "close": "<|im_end|>",
            "content": "text",
        },
    },
}
```

Pada dasarnya, template mendefinisikan **field** dan **deliminator**. Setiap field berkorespondensi dengan sebuah key dalam dict output. Field juga mencakup informasi untuk parsing teks di dalam deliminator mereka. Ada satu hal yang perlu diperhatikan: field `content` tidak memiliki `open`, karena pada SmolLM (dan beberapa model lainnya), field ini tidak ditandai oleh token khusus. Sebaliknya, `content` disimpan di ruang setelah region lain, tetapi sebelum akhir sequence. Dalam template kami, hal ini direpresentasikan sebagai field **implicit / leftover** yang mengambil teks mana pun yang tidak diklaim oleh region lain.

Nama field harus sesuai dengan kunci yang dibaca oleh template chat model, sehingga pesan yang telah diurai dapat ditambahkan ke chat dan dirender kembali. Secara khusus, beri nama field penalaran sebagai `reasoning_content`. Ini adalah kunci standar untuk penalaran dalam dict pesan, dan yang dibaca oleh hampir semua template chat untuk penalaran.

Selain `fields`, template mendukung dua kunci tingkat atas:

- `defaults` (opsional) — Sebuah dict berisi nilai yang sudah terisi di output (misalnya `{"role": "assistant"}`). Kunci di sini selalu dipertahankan dalam output yang di-parse, bahkan jika tidak ada field yang menulis ke dalamnya; kunci lain akan dihapus jika field-nya tidak menangkap apa pun.
- `start_anchor` (str) / `start_anchor_pattern` (str regex) — Menandai di mana pesan asisten saat ini dimulai di dalam prompt chat. Ketika Anda meneruskan `prefix=` ke `parse_response` atau `get_response_parser`, parser akan memotong kanan prefix melewati kemunculan **terakhir** dari anchor ini sebelum memprosesnya, sehingga giliran sebelumnya dalam percakapan multi-turn tidak mencemari state pesan saat ini. Anchor hanya diterapkan pada `prefix`, tidak pernah pada respons/generasi yang Anda parse — beberapa format secara sah memunculkannya kembali di tengah pesan (output harmony gpt-oss membuka setiap channel dengan `<|start|>assistant`), sehingga memotong respons melewati anchor akan menghilangkan penalaran dan panggilan tool milik model itu sendiri. Inilah mengapa generasi saja tidak pernah cukup untuk menjaga terhadap kebocoran riwayat: teruskan prompt sebagai `prefix=`. Untuk model bergaya ChatML, anchor biasanya adalah `"<|im_start|>assistant\n"`. Tepat satu dari `start_anchor` atau `start_anchor_pattern` harus disetel.

Sebagai contoh, diberikan prefiks multi-turn berikut (perhatikan **dua** giliran asisten):

```txt
<|im_start|>user
Hi<|im_end|>
<|im_start|>assistant
Hello!<|im_end|>
<|im_start|>user
Again?<|im_end|>
<|im_start|>assistant
```

parser memotong semua konten hingga **terakhir** `<|im_start|>assistant\n`, sehingga giliran `"Hello!"` sebelumnya dihapus. Aturannya adalah _seluruh konten selain giliran asisten terakhir selalu dibuang._

Sama seperti template chat, template respons disimpan sebagai atribut tokenizer dan disimpan bersama tokenizer. Berbeda dengan template chat, kami menyimpannya di dalam `tokenizer_config.json` dan bukan sebagai file terpisah, karena formatnya cocok secara alami dalam JSON, tidak seperti skrip Jinja untuk template chat.

```python
tokenizer.response_template = template
tokenizer.save_pretrained(...)  # Written as a key in tokenizer_config.json
```

## Lanjutan: Referensi API Field

Setiap field mendukung beberapa kunci. Kita dapat membaginya menjadi dua jenis. Pertama, ada kunci yang mendefinisikan bagaimana field harus ditangkap:

| Kunci             | Tipe               | Tujuan                                                                                       |
|-----------------|--------------------|-----------------------------------------------------------------------------------------------|
| `open`          | str atau list[str]   | String literal yang membuka region ini. Daftar string berarti "cocokkan salah satu dari string-string ini".          |
| `open_pattern`  | str (regex)        | Alternatif regex untuk `open`. Grup bernama menjadi variabel tangkapan yang tersedia untuk `transform`.  |
| `close`         | str atau list[str]   | String literal (atau daftar string) yang menutup region ini. Abaikan untuk menjalankan hingga akhir stream.    |
| `close_pattern` | str (regex)        | Alternatif regex untuk `close`. Grup bernama menjadi variabel tangkapan yang tersedia untuk `transform`. |
| `repeats`       | bool               | Jika true, field tersebut adalah daftar dan setiap kecocokan akan ditambahkan. Default `false`.                         |
| `join`          | str                | Dengan `repeats`, gabungkan hasil ke dalam satu string dengan pemisah ini alih-alih daftar.    |
| `optional`      | bool               | Jika false dan region tidak pernah cocok, kami akan menaikkan error. Default `true`.                     |

Sebuah field harus memiliki **satu dari** `open` atau `open_pattern`, tetapi tidak keduanya, dan hal yang sama berlaku untuk `close` dan `close_pattern`.

Sebuah field dapat mengabaikan `close`/`close_pattern` sepenuhnya, sehingga region tetap terbuka hingga akhir teks yang dihasilkan. Hal ini berguna untuk field terakhir yang berjalan hingga akhir pesan.

Field yang **tidak memiliki** `open` maupun `open_pattern` adalah field **implisit**: field ini aktif setiap kali tidak ada region eksplisit yang terbuka, sehingga menangkap sisa teks. Maksimal satu field yang dapat bersifat implisit. Hal ini paling sering digunakan ketika `content` tidak memiliki tag token khusus, dan hanya ditulis sebagai plaintext setelah field lainnya.

Selain pembuka dan penutup delimitator, Anda juga dapat menentukan `repeats`, yang menunjukkan bahwa field tersebut berupa daftar dan delimitator dapat cocok beberapa kali. Hal ini paling umum terjadi pada pemanggilan tool paralel, ketika model mengeluarkan beberapa pemanggilan tool secara bersamaan:

```python
'<tool_call>{"name": "a", ...}</tool_call><tool_call>{"name": "b", ...}</tool_call>'
# Returns `"tool_calls": [{... "a" ...}, {... "b" ...}]` in a template with repeats: true
```

Namun, tidak semua field berulang harus menjadi list. Beberapa model mengeluarkan beberapa blok `reasoning_content` atau `content` dalam satu pesan, dan output alami untuk hal tersebut adalah satu string yang digabungkan. Menetapkan `join` (string pemisah, sering kali hanya `""`) mengubah field `repeats` dari mengumpulkan list menjadi menggabungkan match-nya:

```python
field = {"reasoning_content": {"open": "<think>", "close": "</think>", "repeats": True, "join": "\n"}}
input = "<think>first</think>...<think>second</think>"
# Returns: {"reasoning_content": "first\nsecond"}
```

Setiap kecocokan dari field `join` harus dapat di-parse menjadi string. Saat streaming, `region_close` tetap membawa nilai dari masing-masing blok; pemisah hanya muncul dalam dict pesan akhir.

Terakhir, Anda dapat menentukan `optional: false` untuk field yang harus ada. Jika field seperti itu tidak ada, kami akan melempar error alih-alih hanya mengembalikan dict pesan tanpa field tersebut.

Akhir dari generasi akan menutup dan memfinalisasi semua region yang masih terbuka, bahkan jika delimiter penutupnya tidak terlihat.

### Menganalisis konten dari sebuah field

Setelah kita mendefinisikan cara menangkap sebuah field, kita juga perlu menentukan cara mengurai teks mentah di dalam tangkapan tersebut. Ada empat kunci yang mengontrol hal ini:

| Kunci              | Tipe         | Tujuan                                                                                  |
|------------------|--------------|------------------------------------------------------------------------------------------|
| `content`        | str          | Tipe konten di dalam region ini. Nilainya secara default adalah `"text"`. Setiap tipe memiliki parser-nya sendiri. |
| `content_args`   | dict         | Argumen yang akan diteruskan ke parser konten untuk wilayah ini.                            |
| `transform`      | dict/list    | Template opsional pasca-parsing yang membentuk ulang tubuh yang telah diurai (lihat **Transform**).          |
| `transform_each` | bool         | Jika true, konten yang diurai harus berupa daftar dan `transform` diterapkan per elemen.       |

Kunci pertama (dan yang paling penting) adalah `content`. Ini menunjukkan tipe konten dari field, yang menentukan parser yang akan digunakan untuk mengubah teks mentah yang ditangkap dalam field menjadi output akhir. `content_args` digunakan untuk mengonfigurasi parser, dan memungkinkan kita mendukung berbagai keanehan format tanpa perlu kode khusus. Kita akan melihat setiap tipe parser dan argumennya secara berurutan.

#### Tipe dasar
`text`, `int`, `float`, dan `bool` adalah tipe dasar. Semua tipe konten ini hanya menghapus spasi lalu melakukan konversi tipe sederhana jika diperlukan. Mereka tidak memiliki `content_args`, kecuali `text` yang mendukung argumen `strip`, yang menghapus spasi dari awal dan akhir teks yang ditangkap, dengan nilai default `true`.

```python
field = {"count": {"open": "<n>", "close": "</n>", "content": "int"}}
input = "<n> 42 </n>"
# Returns: {"count": 42}
```

#### json

Parser `json` mem-parsing teks yang ditangkap sebagai JSON. Ini adalah tulang punggung untuk argumen tool-call dan hal lain yang memiliki struktur bersarang. Parser ini menerima sejumlah `content_args` opsional untuk menangani berbagai cara model merusak JSON di dunia nyata:

- `unquoted_keys` (bool, default `false`): Aktifkan ketika nama key berupa teks mentah tanpa tanda kutip (misalnya `{name: "foo"}`). Berguna untuk model yang menghasilkan literal objek bergaya Javascript alih-alih JSON ketat.
- `string_delims` (list of `[open, close]` pairs, optional): untuk model yang membungkus nilai string dengan delimiter khusus alih-alih `"..."`. Setiap pasangan memberikan penanda pembuka dan penutup.
- `allow_non_json` (bool, default `false`): jika parsing gagal, kembalikan teks mentah yang sudah dibersihkan alih-alih melempar error. Berguna sebagai fallback untuk field di mana model *umumnya* mengeluarkan JSON tetapi sesekali beralih ke teks biasa.

`unquoted_keys` dan `string_delims` keduanya ada untuk menangani model yang menghasilkan output non-standar, yaitu hampir-JSON tetapi tidak sepenuhnya JSON, sehingga Anda seharusnya hanya membutuhkannya untuk segelintir model.

```python
field = {"args": {"open": "<args>", "close": "</args>", "content": "json", "content_args": {"unquoted_keys": True}}}
input = '<args>{city: "London"}</args>'
# Returns: {"args": {"city": "London"}}
```

#### xml-inline

Parser `xml-inline` ditujukan untuk region yang terdiri dari urutan datar tag bergaya XML, di mana setiap tag menjadi satu entri dalam dict. Parser ini paling sering digunakan di dalam field `tool_calls` untuk model yang mengeluarkan setiap argumen sebagai tag tersendiri, bukan sebagai blob JSON:

- `tag_pattern` (str, **wajib**): regex yang mencocokkan satu tag. Harus berisi grup bernama `key` (kunci dict yang dihasilkan) dan `value` (teks mentah yang menjadi nilai dict).
- `value_parser` (dict, opsional): parser konten bersarang yang diterapkan pada setiap `value` yang ditangkap. Sebuah dict dengan `name` (parser-nya, mis. `"json"`, `"int"`) dan `args` opsional (`content_args`-nya). Jika diabaikan, nilai tetap sebagai string mentah.
- `merge_duplicates` (bool, default `false`): ketika kunci yang sama muncul beberapa kali, kumpulkan nilai-nilainya ke dalam sebuah list alih-alih membiarkan kecocokan yang lebih akhir menimpa yang sebelumnya.

Sebagai contoh, Qwen3 mengeluarkan setiap argumen tool-call sebagai tag `<parameter>` tersendiri, dan kami memarsinya seperti ini:

```python
"tool_calls": {
    "open_pattern": r"<tool_call>\s*<function=(?P<name>\w+)>",
    "close": "</tool_call>",
    "repeats": True,
    "content": "xml-inline",
    "content_args": {
        "tag_pattern": r"<parameter=(?P<key>\w+)>\s*(?P<value>.*?)\s*</parameter>",
        "value_parser": {"name": "json", "args": {"allow_non_json": True}},
    },
    "transform": {"type": "function", "function": {"name": "{name}", "arguments": "{content}"}},
}
```

Perhatikan `value_parser` yang bersarang: setiap nilai parameter juga diproses melalui parser `json` (dengan `allow_non_json` sehingga string polos tetap lolos). Memberikan field `tool_calls` di atas input ini:

```python
input = "<tool_call><function=get_weather><parameter=city>London</parameter><parameter=units>celsius</parameter></function></tool_call>"
# Returns: {"tool_calls": [{"type": "function", "function": {"name": "get_weather", "arguments": {"city": "London", "units": "celsius"}}}]}
```

#### kv-lines

Parser `kv-lines` menangani pasangan `key: value` yang dipisahkan baris (bayangkan metadata bergaya YAML atau file `.env`). Setiap baris menjadi satu entri dalam dict yang dihasilkan. Semua argumen bersifat opsional:

- `line_sep` (str, default `"\n"`): pemisah antar pasangan.
- `kv_sep` (str, default `":"`): pemisah antara kunci dan nilainya di dalam satu baris. Hanya kemunculan pertama yang digunakan sebagai titik pemisah, sehingga nilai itu sendiri dapat memuat pemisah tersebut.
- `strip` (bool, default `true`): menghapus spasi di sekitar setiap kunci dan nilai.
- `value_parser` (dict, opsional): parser konten bersarang yang diterapkan ke setiap nilai, dalam format `{"name": ..., "args": ...}` yang sama seperti untuk `xml-inline`. Jika diabaikan, nilai tetap sebagai string mentah.

Baris yang kosong atau tidak berisi `kv_sep` akan dilewati secara diam-diam, sehingga baris kosong yang tidak sengaja ada di area yang ditangkap tetap ditoleransi.

```python
field = {"metadata": {"open": "<meta>", "close": "</meta>", "content": "kv-lines"}}
input = "<meta>name: alice\nage: 30</meta>"
# Returns: {"metadata": {"name": "alice", "age": "30"}}
```

Catatan `age` tetap menyimpan `"30"` sebagai string; tambahkan `value_parser` berupa `{"name": "int"}` untuk mengubahnya menjadi `30`.

### Mengetik argumen pemanggilan alat

Terkadang, parser respons dapat memparse output model dengan tipe yang salah. Misalnya, parser mungkin memparse float `1.5` sebagai "1.50". Hal ini dapat menyebabkan masalah pada tool calling, jika tool mengharapkan argumen dalam satu tipe tetapi menerimanya dalam tipe lain. Untuk menghindari hal ini, Anda dapat meneruskan `tools` dari request ke [parse_response()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.parse_response) atau `ResponseParser` untuk melakukan casting menggunakan `parameters` JSON Schema dari masing-masing tool. Tool diterima dalam format yang sama seperti [apply_chat_template()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template): JSON schema, atau fungsi Python dengan type hints dan docstring yang dikonversi secara otomatis menjadi schema.

```python
tools = [{
    "type": "function",
    "function": {
        "name": "set_alarm",
        "parameters": {
            "type": "object",
            "properties": {
                "hour": {"type": "integer"},
                "enabled": {"type": "boolean"},
                "label": {"type": "string"},
            },
        },
    },
}]
message = parse_response(model_out, template, prefix="", tools=tools)
# message["tool_calls"][0]["function"]["arguments"] ==
# {"hour": 7, "enabled": True, "label": "wake up"}
```

### Transform

Untuk sebagian besar field, kunci `transform` tidak diperlukan. Kunci ini digunakan ketika body yang di-parse perlu dibentuk ulang menjadi output akhir, atau ketika informasi dari delimiter harus digabungkan ke dalam hasil. Paling sering muncul pada field `tool_calls`, karena field ini sering kali memiliki struktur yang kompleks.

`transform` adalah **template**: sebuah dict (atau list) yang menjelaskan bentuk output, di mana string apa pun dalam bentuk `"{name}"` akan diganti dengan nilai yang sesuai. Nilai dapat diakses dari `content` (bagian tubuh yang telah diurai dari region ini) dan grup bernama apa pun yang ditangkap oleh `open_pattern` / `close_pattern`. Kasus penggunaan yang sangat umum adalah membungkus dict panggilan tool dalam dict luar dengan kunci `function`, karena ini merupakan bagian dari format panggilan tool standar kami:

```python
"tool_calls": {
    "open": "<tool_call>",
    "close": "</tool_call>",
    "repeats": True,
    "content": "json",
    "transform": {"type": "function", "function": "{content}"},
},
```

Jadi, output mentah ini:

```txt
<tool_call>{"name": "greet_user", "arguments": {"greeting": "Hi!"}}</tool_call>
```

becomes (catatan `repeats: True` membuat `tool_calls` menjadi daftar):

```json
[{"type": "function", "function": {"name": "greet_user", "arguments": {"greeting": "Hi!"}}}]
```

Placeholder untuk seluruh string seperti `"{content}"` mengembalikan nilai yang dicari dengan tipenya tetap dipertahankan — sehingga di atas, dict JSON yang di-parse langsung disisipkan sebagai nilai dari `function`. Placeholder harus menjadi seluruh string: mencampurkan teks dan placeholder (`"abc {name} def"`) tidak diizinkan. Ini bukan f-string!

Placeholder juga dapat mengambil jalur bertitik seperti `"{content.args}"`, yang mencari `content` lalu masuk ke kunci `args` dari dict yang di-parse. Inilah cara Anda membentuk ulang isi tool-call yang nama kuncinya tidak sesuai dengan format standar kami. Misalnya, model yang mengeluarkan `{"name": ..., "args": ...}` perlu mengganti nama `args` menjadi `arguments`:

```python
"tool_calls": {
    "open": "<tool>",
    "close": "</tool>",
    "repeats": True,
    "content": "json",
    "transform": {"type": "function", "function": {"name": "{content.name}", "arguments": "{content.args}"}},
},
```

Path yang tidak dapat di-resolve (di sini, panggilan tool yang body-nya tidak memiliki `args`) akan memicu error alih-alih mengeluarkan panggilan tool yang tidak valid.

`transform` cukup serbaguna, yang menjadi kebutuhan ketika format output model sangat berbeda dari API standar kami. GPT-OSS adalah contoh yang baik — model ini menyematkan nama fungsi di header channel, bukan di body JSON, sehingga kami harus menangkapnya dengan named group di `open_pattern` dan menggabungkannya dengan `content` di dalam transform. Semua named group di `open_pattern` dan `close_pattern` menjadi tersedia sebagai variabel di samping `content`:

```python
"tool_calls": {
    "open_pattern": r"<\|channel\|>commentary to=functions\.(?P<name>\w+).*?<\|message\|>",
    "close": "<|call|>",
    "repeats": True,
    "content": "json",
    "transform": {"type": "function", "function": {"name": "{name}", "arguments": "{content}"}},
},
```

Nama fungsi berada di header channel, bukan di body JSON, jadi ini:

```txt
<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location": "San Francisco, CA"}<|call|>
```

menjadi:

```json
[{"type": "function", "function": {"name": "get_current_weather", "arguments": {"location": "San Francisco, CA"}}}]
```

Kadang-kadang, konten terparse dari sebuah field *sendiri* merupakan daftar record dan Anda ingin mengubah bentuk masing-masing record. Template Cohere adalah contoh yang baik: template ini mengeluarkan semua tool call di dalam satu array JSON, sehingga kami mengatur `transform_each: True` untuk menerapkan transformasi per elemen. Kunci dari setiap elemen array akan diurai ke dalam scope template, sehingga `"{tool_name}"` akan mencari `tool_name` di elemen saat ini:

```python
"tool_calls": {
    "open": "<|START_ACTION|>",
    "close": "<|END_ACTION|>",
    "content": "json",
    "transform_each": True,
    "transform": {"type": "function", "function": {"name": "{tool_name}", "arguments": "{parameters}"}},
},
```

Ini akan mengonversi output seperti ini:

```json
[
    {"tool_name": "greet_user", "parameters": {"greeting": "Hi!"}},
    {"tool_name": "search", "parameters": {"query": "weather tomorrow"}}
]
```

Menjadi output seperti ini, yang sesuai dengan API standar kami:

```json
[
    {"type": "function", "function": {"name": "greet_user", "arguments": {"greeting": "Hi!"}}},
    {"type": "function", "function": {"name": "search", "arguments": {"query": "weather tomorrow"}}}
]
```

Flag `transform_each` hanya diperlukan ketika `content` sudah berupa list; untuk kasus yang lebih umum di mana setiap match menyumbang satu elemen (dan `repeats: True` mengakumulasi mereka), maka transform akan diterapkan ke setiap elemen secara default.

## Pengembang framework: Portabilitas regex

`open_pattern`, `close_pattern`, dan `start_anchor_pattern` adalah string regex. Bagi sebagian besar pengguna, bahkan bagi sebagian besar pengembang model, ini seharusnya bukan masalah, tetapi jika Anda adalah pengembang yang menulis implementasi parsing respons dalam bahasa lain, Anda perlu memahami detail implementasi kami. Bagian ini ditujukan untuk semua orang yang harus mengimplementasikan parser Jinja lengkap agar chat templating non-Python dapat berfungsi - kami berharap bahwa jika Anda mengikuti panduan sederhana di bawah ini, maka template respons akan jauh lebih mudah:

- Kami menggunakan modul [`regex`](https://pypi.org/project/regex/) Python untuk semua regex yang digunakan dalam parsing chat. Karena semua string Python3 adalah unicode, **semua kecocokan regex kami sadar unicode**. Hal ini terutama memengaruhi karakter umum seperti `\w`. Pastikan Anda mengatur flag unicode yang relevan di engine Anda.
- Kami mengompilasi semua regex dengan `re.DOTALL` diaktifkan dan `re.MULTILINE` dinonaktifkan, sehingga `.` cocok dengan `\n` tetapi `^` dan `$` hanya cocok dengan awal/akhir seluruh input, bukan baris baru.
- Kami menggunakan sintaks `(?P<name>...)` untuk grup bernama. Implementasi regex lain memiliki sintaks grup tangkapan bernama yang sangat berbeda, sehingga Anda mungkin perlu mencari pola ini di dalam regex dan menulis ulang agar sesuai dengan implementasi lokal Anda.
- Kami menggunakan pencocokan regex parsial untuk menentukan kapan data dapat dikeluarkan. Hal ini diperlukan karena akhir sebuah region dapat terdiri dari beberapa token, dan kami tidak ingin mengeluarkan pemisah akhir-region tersebut, sehingga kami menahan token hingga kami yakin bahwa token tersebut berada di dalam region dan bukan bagian dari batas. Artinya, setiap kali regex akhir region memiliki pencocokan parsial, kami menahan data hingga regex tersebut berhasil dicocokkan atau gagal. Jika mesin regex Anda tidak mendukung pencocokan parsial, Anda tetap dapat mengimplementasikan template respons, tetapi mungkin perlu mencari solusi lain untuk masalah ini. Satu pendekatan sederhana adalah dengan menahan region-region ini / mengeluarkannya sebagai `dirty` hingga Anda secara definitif melihat pemisah akhirnya.
- Mesin regex Anda mungkin (jarang) tidak mendukung lookaround seperti `(?!...)`. Meskipun fitur ini tidak umum digunakan dalam template respons, mereka dapat muncul dan kami memang mendukungnya! Anda mungkin perlu melempar error dalam kasus tersebut, atau mengekstrak lookaround secara manual dan menegakkannya dalam kode Anda ketika mesin regex menemukan kemungkinan kecocokan.
- Fitur lanjutan lainnya seperti backreferences, atomic groups, possessive quantifiers, recursion, dan sebagainya umumnya tidak digunakan dalam template respons. Kami akan berusaha mencegah para pengembang model untuk menggunakannya, sehingga Anda dapat mengabaikannya dengan aman.

