| 1 | # vllm/parser |
| 2 | |
| 3 | Model-output parsing for the serving layer. `Parser` (`abstract_parser.py`) |
| 4 | unifies reasoning extraction and tool-call extraction behind one object; the |
| 5 | serving layer calls `parse` / `parse_delta` and `is_reasoning_end` on it. |
| 6 | |
| 7 | ## Layout |
| 8 | |
| 9 | - `abstract_parser.py` — `Parser`, and `DelegatingParser` for wrapping a legacy |
| 10 | `ReasoningParser` + `ToolParser` pair. |
| 11 | - `parser_manager.py` — resolves parser names to classes. |
| 12 | - `engine/` — the declarative parser engine. A `ParserEngineConfig` |
| 13 | (`parser_engine_config.py`) is a set of terminals, transitions and content |
| 14 | events; `parser_engine.py` and `streaming_parser_engine.py` drive it for the |
| 15 | non-streaming and streaming paths; `token_id_scanner.py` pre-lexes |
| 16 | special-token ids and `incremental_lexer.py` lexes text; `adapters.py` |
| 17 | exposes an engine through the legacy reasoning/tool parser interfaces. |
| 18 | - `<model>.py` — one file per model family. Most subclass `ParserEngine` |
| 19 | (`deepseek_v4.py`, `qwen3.py`, ...); a few are `DelegatingParser` wrappers |
| 20 | over legacy parsers (`harmony.py`, `kimi_k3.py`). |
| 21 | |
| 22 | ## Guidelines |
| 23 | |
| 24 | - A new parser either subclasses `ParserEngine` with a declarative config, or |
| 25 | subclasses `Parser` and implements `parse` / `parse_delta` directly. Use the |
| 26 | engine when the format is expressible as terminals and transitions, and |
| 27 | subclass an existing config when it is a variant of one (`seed_oss.py`, |
| 28 | `ling3.py`). `DelegatingParser` exists for backward compatibility with the |
| 29 | separate `ReasoningParser` / `ToolParser` classes; do not use it for new |
| 30 | formats. |
| 31 | - Keep a model-specific fix inside that model's `<model>.py` where possible. |
| 32 | Change `engine/` or `abstract_parser.py` only when the behavior is wrong for |
| 33 | every parser, and say so in the PR. |
| 34 | - Text emitted in a state with no `content_events` entry is discarded. Make |
| 35 | that deliberate when adding a state. |
| 36 | - Special tokens reach the engine as token ids, not text. A text terminal that |
| 37 | spans a special token never matches in streaming; list it in |
| 38 | `token_id_terminals`. |
| 39 | - Comment only where the code alone would leave a reader with a question — |
| 40 | a non-obvious transition, a deliberate swallow, a model quirk being worked |
| 41 | around. Keep it minimal and concise. |