main
py 577 lines 19.9 KB
Raw
1 # SPDX-License-Identifier: Apache-2.0
2 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
3 # ruff: noqa
4
5 """Text encoding adapted from the DeepSeek V4.1 reference encoder.
6
7 Message normalization and serving controls live in deepseek_v41.py.
8 """
9
10 import copy
11 import json
12 from typing import Any, Dict, List, Optional, Union
13
14 bos_token: str = "<|begin▁of▁sentence|>"
15 eos_token: str = "<|end▁of▁sentence|>"
16 thinking_start_token: str = "<think>"
17 thinking_end_token: str = "</think>"
18 dsml_token: str = "|DSML|"
19
20 USER_SP_TOKEN = "<|User|>"
21 ASSISTANT_SP_TOKEN = "<|Assistant|>"
22 LATEST_REMINDER_SP_TOKEN = "<|latest_reminder|>"
23 IMAGE_PLACEHOLDER = "<|deepseek_image|>"
24
25 DS_TASK_SP_TOKENS = {
26 "action": "<|action|>",
27 "query": "<|query|>",
28 "authority": "<|authority|>",
29 "domain": "<|domain|>",
30 "title": "<|title|>",
31 "read_url": "<|read_url|>",
32 }
33 VALID_TASKS = set(DS_TASK_SP_TOKENS.keys())
34
35 system_msg_template: str = "{content}"
36 user_msg_template: str = "{content}"
37 latest_reminder_msg_template: str = "{content}"
38 assistant_msg_template: str = "{reasoning}{content}{tool_calls}" + eos_token
39 assistant_msg_wo_eos_template: str = "{reasoning}{content}{tool_calls}"
40 thinking_template: str = "{reasoning_content}"
41
42 response_format_template: str = (
43 "## Response Format:\n\n"
44 "You MUST strictly adhere to the following schema to reply:\n{schema}"
45 )
46 tool_output_template: str = "<tool_result>{content}</tool_result>"
47
48
49 def to_json(value: Any) -> str:
50 """Serialize a value to JSON string."""
51 try:
52 return json.dumps(value, ensure_ascii=False)
53 except:
54 return json.dumps(value, ensure_ascii=True)
55
56
57 def tools_from_openai_format(tools):
58 """Extract function definitions from OpenAI-format tool list."""
59 return [tool["function"] for tool in tools]
60
61
62 def tool_calls_from_openai_format(tool_calls):
63 """Convert OpenAI-format tool calls to internal format."""
64 return [
65 {
66 "name": tool_call["function"]["name"],
67 "arguments": tool_call["function"]["arguments"],
68 }
69 for tool_call in tool_calls
70 ]
71
72
73 def merge_tool_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
74 """
75 Merge tool messages into the preceding user message using content_blocks format.
76
77 DeepSeek-V4.1 does not have a standalone "tool" role; instead, tool results
78 are encoded as <tool_result> blocks within user messages.
79 """
80 merged: List[Dict[str, Any]] = []
81
82 for msg in messages:
83 msg = copy.deepcopy(msg)
84 role = msg.get("role")
85
86 if role == "tool":
87 # Convert tool message to a user message with tool_result block
88 tool_block = {
89 "type": "tool_result",
90 "tool_use_id": msg.get("tool_call_id", ""),
91 "content": msg.get("content", ""),
92 }
93 # Merge into previous message if it's already a user (merged tool)
94 if (
95 merged
96 and merged[-1].get("role") == "user"
97 and "content_blocks" in merged[-1]
98 ):
99 merged[-1]["content_blocks"].append(tool_block)
100 else:
101 merged.append(
102 {
103 "role": "user",
104 "content_blocks": [tool_block],
105 }
106 )
107 elif role == "user":
108 content_blocks = msg.get("content_blocks")
109 if content_blocks is None:
110 content_blocks = [{"type": "text", "text": msg.get("content", "")}]
111 if (
112 merged
113 and merged[-1].get("role") == "user"
114 and "content_blocks" in merged[-1]
115 and merged[-1].get("task") is None
116 ):
117 merged[-1]["content_blocks"].extend(content_blocks)
118 else:
119 # Preserve structured content and all message-level metadata.
120 new_msg = msg
121 new_msg["content_blocks"] = content_blocks
122 merged.append(new_msg)
123 else:
124 merged.append(msg)
125
126 return merged
127
128
129 def sort_tool_results_by_call_order(
130 messages: List[Dict[str, Any]],
131 ) -> List[Dict[str, Any]]:
132 """
133 Sort tool_result blocks within user messages by the order of tool_calls
134 in the preceding assistant message.
135 """
136 last_tool_call_order: Dict[str, int] = {}
137
138 for msg in messages:
139 role = msg.get("role")
140 if role == "assistant" and msg.get("tool_calls"):
141 last_tool_call_order = {}
142 for idx, tc in enumerate(msg["tool_calls"]):
143 tc_id = tc.get("id") or tc.get("function", {}).get("id", "")
144 if tc_id:
145 last_tool_call_order[tc_id] = idx
146
147 elif role == "user" and msg.get("content_blocks"):
148 tool_blocks = [
149 b for b in msg["content_blocks"] if b.get("type") == "tool_result"
150 ]
151 if len(tool_blocks) > 1 and last_tool_call_order:
152 sorted_blocks = sorted(
153 tool_blocks,
154 key=lambda b: last_tool_call_order.get(b.get("tool_use_id", ""), 0),
155 )
156 sorted_idx = 0
157 new_blocks = []
158 for block in msg["content_blocks"]:
159 if block.get("type") == "tool_result":
160 new_blocks.append(sorted_blocks[sorted_idx])
161 sorted_idx += 1
162 else:
163 new_blocks.append(block)
164 msg["content_blocks"] = new_blocks
165
166 return messages
167
168
169 SYSTEM_SP_TOKEN = "<|System|>"
170
171 tool_calls_block_name: str = " calls"
172 tool_call_tag_name: str = " invoke"
173 tool_parameter_tag_name: str = " parameter"
174 tool_call_template: str = '<{dsml_token}{tool_call_tag_name} name="{name}">\n{arguments}\n</{dsml_token}{tool_call_tag_name}>'
175 tool_calls_template = (
176 "<{dsml_token}{tc_block_name}>\n{tool_calls}\n</{dsml_token}{tc_block_name}>"
177 )
178
179 REASONING_EFFORT_TEMPLATE = (
180 "Reasoning Effort: {budget} "
181 "(range 1-100, the higher the value, the more thorough the reasoning)\n\n"
182 )
183 REASONING_EFFORT_MAPPINGS: Dict[str, int] = {
184 "low": 50,
185 "high": 75,
186 "xhigh": 75,
187 "max": 100,
188 }
189
190 DEFAULT_REASONING_EFFORT = "high"
191
192
193 def render_reasoning_effort(
194 index: int,
195 thinking_mode: str,
196 effort: Union[str, int, None],
197 ) -> str:
198 """Render the V4.1 numeric reasoning effort prefix (thinking mode, index 0 only)."""
199 if effort is None:
200 effort = DEFAULT_REASONING_EFFORT
201 assert (
202 type(effort) is int and 1 <= effort <= 100
203 ) or effort in REASONING_EFFORT_MAPPINGS, (
204 "Invalid reasoning effort for deepseek_v41: "
205 f"{effort}, should be int within [1,100] or {list(REASONING_EFFORT_MAPPINGS)}"
206 )
207 if type(effort) is str:
208 effort = REASONING_EFFORT_MAPPINGS[effort]
209 if index == 0 and thinking_mode == "thinking":
210 return REASONING_EFFORT_TEMPLATE.format(budget=effort)
211 return ""
212
213
214 TOOLS_TEMPLATE = """## Tools
215
216 You have access to a set of tools to help answer the user's question. You can invoke tools by writing a "<{dsml_token}{tc_block_name}>" block like the following:
217
218 <{dsml_token}{tc_block_name}>
219 <{dsml_token}{tool_call_tag_name} name="$TOOL_NAME">
220 <{dsml_token}{tool_parameter_tag_name} name="$PARAMETER_NAME" string="true|false">$PARAMETER_VALUE</{dsml_token}{tool_parameter_tag_name}>
221 ...
222 </{dsml_token}{tool_call_tag_name}>
223 <{dsml_token}{tool_call_tag_name} name="$TOOL_NAME2">
224 ...
225 </{dsml_token}{tool_call_tag_name}>
226 </{dsml_token}{tc_block_name}>
227
228 String parameters should be specified as is and set `string="true"`. For all other types (numbers, booleans, arrays, objects), pass the value in JSON format and set `string="false"`.
229
230 If thinking_mode is enabled (triggered by {thinking_start_token}), you MUST output your complete reasoning inside {thinking_start_token}...{thinking_end_token} BEFORE any tool calls or final response.
231
232 Otherwise, output directly after {thinking_end_token} with tool calls or final response.
233
234 ### Available Tool Schemas
235
236 {tool_schemas}
237
238 You MUST strictly follow the above defined tool name and parameter schemas to invoke tool calls.
239 """
240
241
242 def render_tools(tools: List[Dict[str, Union[str, Dict[str, Any]]]]) -> str:
243 """Render tool schemas into the V4.1 system prompt format."""
244 tools_json = [to_json(t) for t in tools]
245
246 return TOOLS_TEMPLATE.format(
247 tool_schemas="\n".join(tools_json),
248 dsml_token=dsml_token,
249 tc_block_name=tool_calls_block_name,
250 tool_call_tag_name=tool_call_tag_name,
251 tool_parameter_tag_name=tool_parameter_tag_name,
252 thinking_start_token=thinking_start_token,
253 thinking_end_token=thinking_end_token,
254 )
255
256
257 def encode_arguments_to_dsml(tool_call: Dict[str, Any]) -> str:
258 """Encode tool call arguments into V4.1 DSML parameter format."""
259 p_dsml_template = (
260 '<{dsml_token}{tool_parameter_tag_name} name="{key}" string="{is_str}">'
261 "{value}</{dsml_token}{tool_parameter_tag_name}>"
262 )
263 P_dsml_strs = []
264
265 arguments = tool_call["arguments"]
266 if not isinstance(arguments, dict):
267 # Tolerate JSON strings, including double-encoded ones.
268 for _ in range(2):
269 if isinstance(arguments, str):
270 try:
271 arguments = json.loads(arguments)
272 except Exception:
273 break
274 else:
275 break
276 if not isinstance(arguments, dict):
277 arguments = {"arguments": tool_call["arguments"]}
278
279 for k, v in arguments.items():
280 P_dsml_strs.append(
281 p_dsml_template.format(
282 dsml_token=dsml_token,
283 tool_parameter_tag_name=tool_parameter_tag_name,
284 key=k,
285 is_str="true" if isinstance(v, str) else "false",
286 value=v if isinstance(v, str) else to_json(v),
287 )
288 )
289
290 return "\n".join(P_dsml_strs)
291
292
293 def find_last_user_index(messages: List[Dict[str, Any]]) -> int:
294 """
295 Find the index of the last user/developer message.
296
297 V4.1 supports mid-conversation system messages, which count as user
298 messages for the purposes of the assistant generation header.
299 """
300 last_user_index = -1
301 for idx in range(len(messages) - 1, -1, -1):
302 role = messages[idx].get("role")
303 if role in ["user", "developer"] or (role == "system" and idx > 0):
304 last_user_index = idx
305 break
306 return last_user_index
307
308
309 def render_message(
310 index: int,
311 messages: List[Dict[str, Any]],
312 thinking_mode: str,
313 drop_thinking: bool = True,
314 reasoning_effort: Union[str, int, None] = None,
315 ) -> str:
316 """
317 Render a single message at the given index into its V4.1 encoded string form.
318 """
319 assert 0 <= index < len(messages)
320 assert thinking_mode in ["chat", "thinking"], (
321 f"Invalid thinking_mode `{thinking_mode}`"
322 )
323
324 msg = messages[index]
325 last_user_idx = find_last_user_index(messages)
326
327 role = msg.get("role")
328 content = msg.get("content")
329 tools = msg.get("tools")
330 response_format = msg.get("response_format")
331 tool_calls = msg.get("tool_calls")
332 reasoning_content = msg.get("reasoning_content")
333 wo_eos = msg.get("wo_eos", False)
334
335 if tools:
336 tools = tools_from_openai_format(tools)
337 if tool_calls:
338 tool_calls = tool_calls_from_openai_format(tool_calls)
339
340 # Reasoning effort prefix (thinking mode, index 0 only)
341 reasoning_effort_prompt = render_reasoning_effort(
342 index, thinking_mode, reasoning_effort
343 )
344 # System token leads the conversation when there is a reasoning effort prompt
345 # or the first message is a system message.
346 prompt = (
347 SYSTEM_SP_TOKEN
348 if index == 0 and (reasoning_effort_prompt or role == "system")
349 else ""
350 )
351 prompt += reasoning_effort_prompt
352
353 if role == "system":
354 if index > 0:
355 # Mid-conversation system message
356 prompt += SYSTEM_SP_TOKEN
357 prompt += system_msg_template.format(content=content or "")
358 if tools:
359 prompt += "\n\n" + render_tools(tools)
360 if response_format:
361 prompt += "\n\n" + response_format_template.format(
362 schema=to_json(response_format)
363 )
364
365 elif role == "developer":
366 assert content, f"Invalid message for role `{role}`: {msg}"
367
368 content_developer = USER_SP_TOKEN
369 content_developer += content
370
371 if tools:
372 content_developer += "\n\n" + render_tools(tools)
373 if response_format:
374 content_developer += "\n\n" + response_format_template.format(
375 schema=to_json(response_format)
376 )
377
378 prompt += user_msg_template.format(content=content_developer)
379
380 elif role == "user":
381 prompt += USER_SP_TOKEN
382
383 # Handle content blocks (tool results mixed with text)
384 content_blocks = msg.get("content_blocks")
385 if content_blocks:
386 parts = []
387 for block in content_blocks:
388 block_type = block.get("type")
389 if block_type == "text":
390 parts.append(block.get("text", ""))
391 elif block_type == "tool_result":
392 tool_content = block.get("content", "")
393 if isinstance(tool_content, list):
394 text_parts = []
395 for b in tool_content:
396 if b.get("type") == "text":
397 text_parts.append(b.get("text", ""))
398 else:
399 text_parts.append(f"[Unsupported {b.get('type')}]")
400 tool_content = "\n\n".join(text_parts)
401 parts.append(tool_output_template.format(content=tool_content))
402 else:
403 parts.append(f"[Unsupported {block_type}]")
404 prompt += "\n\n".join(parts)
405 else:
406 prompt += content or ""
407
408 elif role == "latest_reminder":
409 prompt += LATEST_REMINDER_SP_TOKEN + latest_reminder_msg_template.format(
410 content=content
411 )
412
413 elif role == "tool":
414 raise NotImplementedError(
415 "deepseek_v41 merges tool messages into user; please preprocess with merge_tool_messages()"
416 )
417
418 elif role == "assistant":
419 thinking_part = ""
420 tc_content = ""
421
422 if tool_calls:
423 tc_list = [
424 tool_call_template.format(
425 dsml_token=dsml_token,
426 tool_call_tag_name=tool_call_tag_name,
427 name=tc.get("name"),
428 arguments=encode_arguments_to_dsml(tc),
429 )
430 for tc in tool_calls
431 ]
432 tc_content += "\n\n" + tool_calls_template.format(
433 dsml_token=dsml_token,
434 tool_calls="\n".join(tc_list),
435 tc_block_name=tool_calls_block_name,
436 )
437
438 summary_content = content or ""
439 rc = reasoning_content or ""
440
441 # Check if previous message has a task - if so, this is a task output (no thinking)
442 prev_has_task = index - 1 >= 0 and messages[index - 1].get("task") is not None
443
444 if thinking_mode == "thinking" and not prev_has_task:
445 if not drop_thinking or index > last_user_idx:
446 thinking_part = (
447 thinking_template.format(reasoning_content=rc) + thinking_end_token
448 )
449 else:
450 thinking_part = ""
451
452 if wo_eos:
453 prompt += assistant_msg_wo_eos_template.format(
454 reasoning=thinking_part,
455 content=summary_content,
456 tool_calls=tc_content,
457 )
458 else:
459 prompt += assistant_msg_template.format(
460 reasoning=thinking_part,
461 content=summary_content,
462 tool_calls=tc_content,
463 )
464 else:
465 raise NotImplementedError(f"Unknown role: {role}")
466
467 # Append transition tokens based on what follows
468 if index + 1 < len(messages) and messages[index + 1].get("role") not in [
469 "assistant",
470 "latest_reminder",
471 ]:
472 return prompt
473
474 task = messages[index].get("task")
475 if task is not None:
476 # Task special token for internal classification tasks
477 assert task in VALID_TASKS, (
478 f"Invalid task: '{task}'. Valid tasks are: {list(VALID_TASKS)}"
479 )
480 task_sp_token = DS_TASK_SP_TOKENS[task]
481
482 if task != "action":
483 # Non-action tasks: append task sp token directly after the message
484 prompt += task_sp_token
485 else:
486 # Action task: append Assistant + thinking token + action sp token
487 prompt += ASSISTANT_SP_TOKEN
488 prompt += (
489 thinking_end_token
490 if thinking_mode != "thinking"
491 else thinking_start_token
492 )
493 prompt += task_sp_token
494
495 elif messages[index].get("role") in ["user", "developer"] or (
496 messages[index].get("role") == "system" and index > 0
497 ):
498 # Normal generation: append Assistant + thinking token
499 # (mid-conversation system messages also trigger the assistant header)
500 prompt += ASSISTANT_SP_TOKEN
501 if not drop_thinking and thinking_mode == "thinking":
502 prompt += thinking_start_token
503 elif drop_thinking and thinking_mode == "thinking" and index >= last_user_idx:
504 prompt += thinking_start_token
505 else:
506 prompt += thinking_end_token
507
508 return prompt
509
510
511 def _drop_thinking_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
512 """
513 Drop reasoning_content and non-essential messages before the last user message.
514 Same as V4, but uses the V4.1 last-user definition (mid systems count).
515 """
516 last_user_idx = find_last_user_index(messages)
517 result = []
518 keep_roles = {"user", "system", "tool", "latest_reminder", "direct_search_results"}
519
520 for idx, msg in enumerate(messages):
521 role = msg.get("role")
522 if role in keep_roles or idx >= last_user_idx:
523 result.append(msg)
524 elif role == "assistant":
525 msg = copy.copy(msg)
526 msg.pop("reasoning_content", None)
527 result.append(msg)
528 # developer and other roles before last_user_idx are dropped
529
530 return result
531
532
533 def encode_messages(
534 messages: List[Dict[str, Any]],
535 thinking_mode: str,
536 context: Optional[List[Dict[str, Any]]] = None,
537 drop_thinking: bool = True,
538 add_default_bos_token: bool = True,
539 reasoning_effort: Union[str, int, None] = None,
540 ) -> str:
541 """Encode preprocessed (text-only) messages into the V4.1 prompt format."""
542 context = context if context else []
543
544 # Preprocess: merge tool messages and sort tool results
545 messages = merge_tool_messages(messages)
546 messages = sort_tool_results_by_call_order(context + messages)[len(context) :]
547 if context:
548 context = merge_tool_messages(context)
549 context = sort_tool_results_by_call_order(context)
550
551 full_messages = context + messages
552
553 prompt = bos_token if add_default_bos_token and len(context) == 0 else ""
554
555 # Resolve drop_thinking: if any message has tools defined, don't drop thinking
556 effective_drop_thinking = drop_thinking
557 if any(m.get("tools") for m in full_messages):
558 effective_drop_thinking = False
559
560 if thinking_mode == "thinking" and effective_drop_thinking:
561 full_messages = _drop_thinking_messages(full_messages)
562 num_to_render = len(full_messages) - len(_drop_thinking_messages(context))
563 context_len = len(full_messages) - num_to_render
564 else:
565 num_to_render = len(messages)
566 context_len = len(context)
567
568 for idx in range(num_to_render):
569 prompt += render_message(
570 idx + context_len,
571 full_messages,
572 thinking_mode=thinking_mode,
573 drop_thinking=effective_drop_thinking,
574 reasoning_effort=reasoning_effort,
575 )
576
577 return prompt