apps/FastDeploy
1
0
Fork 0
mirror of https://github.com/PaddlePaddle/FastDeploy.git synced 2026-04-23 00:17:25 +08:00
Code Issues Actions 19 Packages Projects Releases Wiki Activity

[Doc] add chat_template_kwagrs and update params docs (#3103)

Browse Source 
* add chat_template_kwagrs and update params docs

* add chat_template_kwagrs and update params docs

* update enable_thinking

* pre-commit

* update test case

---------

Co-authored-by: Jiang-Jia-Jun <163579578+Jiang-Jia-Jun@users.noreply.github.com>
This commit is contained in:
LiqinruiG
2025-07-31 19:44:06 +08:00
committed by GitHub
parent 22cab724e8
commit 25005fee30
11 changed files with 648 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/online_serving/README.md
+295 -27
View File
@@ -21,9 +21,10 @@ python -m fastdeploy.entrypoints.openai.api_server \
服务部署时的命令行更多使用方式参考[参数说明](../parameters.md)。
## 发送用户请求
## Chat Completion API
FastDeploy 接口兼容 OpenAI 的 Chat Completion API，用户可以通过 OpenAI 协议发送用户请求。
FastDeploy 接口兼容 OpenAI 协议，可以直接使用 OpenAI 的请求方式发送用户请求。
### 发送用户请求
使用 curl 命令发送用户请求示例如下：
@@ -71,32 +72,124 @@ for chunk in response:
print('\n')
```
关于 OpenAI 协议的说明可参考文档 [OpenAI Chat Compeltion API](https://platform.openai.com/docs/api-reference/chat/create)。
关于 OpenAI 协议的说明可参考文档 [OpenAI Chat Completion API](https://platform.openai.com/docs/api-reference/chat/create)。
## 参数差异
### 请求参数差异
FastDeploy 与 OpenAI 协议的请求参数差异如下，其余请求参数会被忽略：
- `prompt` (仅支持 `v1/completions` 接口)
- `messages` (仅支持 `v1/chat/completions` 接口)
- `logprobs`: Optional[bool] = False (仅支持 `v1/chat/completions` 接口)
- `top_logprobs`: Optional[int] = None (仅支持 `v1/chat/completions` 接口。如果使用这个参数必须设置logprobs为True，取值大于等于0小于20)
- `frequency_penalty`: Optional[float] = 0.0
- `max_tokens`: Optional[int] = 16
- `presence_penalty`: Optional[float] = 0.0
- `stream`: Optional[bool] = False
- `stream_options`: Optional[StreamOptions] = None
- `temperature`: Optional[float] = None
- `top_p`: Optional[float] = None
- `extra_body`: Optional[dict] = None (仅在 v1/chat/compeltions 中支持，用于配置额外参数, 如 `extra_body={"enable_thinking": True}`)
- `min_tokens`: Optional[int] = 1 最小生成的Token个数
- `reasoning_max_tokens`: Optional[int] = None 思考内容最大Token数，默认与max_tokens一致
- `enable_thinking`: Optional[bool] = True 支持深度思考的模型是否打开思考
- `repetition_penalty`: Optional[float] = None: 直接对重复生成的token进行惩罚的系数（>1时惩罚重复，<1时鼓励重复）
- `return_token_ids`: Optional[bool] = False: 是否返回 token id 列表
- `include_stop_str_in_output`: Optional[bool] = False: 是否返回结束符
- `top_k`: Optional[bool] = None: TopK-TopP采样参数，参考[采样说明](../features/sampling.md)
### 兼容OpenAI 参数
```python
messages: Union[List[Any], List[int]]
# 输入消息列表，可以是文本消息（`List[Any]`，通常为 `List[dict]`）或 token ID 列表（`List[int]`）。
> 注: 若为多模态模型 由于思考链默认打开导致输出过长，max tokens 可以设置为模型最长输出，或使用默认值。
tools: Optional[List[ChatCompletionToolsParam]] = None
# 工具调用配置列表，用于启用函数调用（Function Calling）或工具使用（如 ReAct 框架）。
model: Optional[str] = "default"
# 指定使用的模型名称或版本，默认值为 `"default"`（可能指向基础模型）。
frequency_penalty: Optional[float] = None
# 频率惩罚系数，降低重复生成相同 token 的概率（`>1.0` 抑制重复，`<1.0` 鼓励重复，默认 `None` 禁用）。
logprobs: Optional[bool] = False
# 是否返回每个生成 token 的对数概率（log probabilities），用于调试或分析。
top_logprobs: Optional[int] = 0
# 返回每个生成位置概率最高的 `top_logprobs` 个 token 及其对数概率（默认 `0` 表示不返回）。
max_tokens: Optional[int] = Field(
default=None,
deprecated="max_tokens is deprecated in favor of the max_completion_tokens field",
)
# 已弃用：生成的最大 token 数（建议改用 `max_completion_tokens`）。
max_completion_tokens: Optional[int] = None
# 生成的最大 token 数（推荐替代 `max_tokens`），默认无限制（受模型上下文窗口限制）。
presence_penalty: Optional[float] = None
# 存在惩罚系数，降低新主题（未出现过的话题）的生成概率（`>1.0` 抑制新话题，`<1.0` 鼓励新话题，默认 `None` 禁用）。
stream: Optional[bool] = False
# 是否启用流式输出（逐 token 返回结果），默认 `False`（一次性返回完整结果）。
stream_options: Optional[StreamOptions] = None
# 流式输出的额外配置（如分块大小、超时等），需参考 `StreamOptions` 的具体定义。
temperature: Optional[float] = None
# 温度系数，控制生成随机性（`0.0` 确定性生成，`>1.0` 更随机，默认 `None` 使用模型默认值）。
top_p: Optional[float] = None
# 核采样（nucleus sampling）阈值，只保留概率累计超过 `top_p` 的 token（默认 `None` 禁用）。
response_format: Optional[AnyResponseFormat] = None
# 指定输出格式（如 JSON、XML 等），需传入预定义的格式配置对象。
user: Optional[str] = None
# 用户标识符，用于跟踪或区分不同用户的请求（默认 `None` 不传递）。
metadata: Optional[dict] = None
# 附加元数据，用于传递自定义信息（如请求 ID、调试标记等）。
```
### FastDeploy 增加额外参数
> 注：
使用 curl 命令发送请求时， 可以直接使用以下参数；
使用openai.Client 发送请求时，需要使用将以下参数放入 `extra_body` 参数中， 如：`extra_body={"chat_template_kwargs": {"enable_thinking":True}, "include_stop_str_in_output": True}`。
额外采样参数的支持如下：
```python
top_k: Optional[int] = None
# 限制每一步生成时只考虑概率最高的 K 个 token，用于控制随机性（默认 None 表示不限制）。
min_p: Optional[float] = None
# 核采样（nucleus sampling）阈值，只保留概率累计超过 min_p 的 token（默认 None 表示禁用）。
min_tokens: Optional[int] = None
# 强制生成的最小 token 数，避免过早截断（默认 None 表示不限制）。
include_stop_str_in_output: Optional[bool] = False
# 是否在输出中包含停止符（stop string）的内容（默认 False，即遇到停止符时截断输出）。
bad_words: Optional[List[str]] = None
# 禁止生成的词汇列表（例如敏感词），模型会避免输出这些词（默认 None 表示不限制）。
repetition_penalty: Optional[float] = None
# 重复惩罚系数，降低已生成 token 的重复概率（>1.0 抑制重复，<1.0 鼓励重复，默认 None 表示禁用）。
```
其他参数的支持如下：
```python
chat_template_kwargs: Optional[dict] = None
# 传递给聊天模板（chat template）的额外参数，用于自定义对话格式（默认 None）。
reasoning_max_tokens: Optional[int] = None
# 推理（如 CoT, 思维链）过程中生成的最大 token 数（默认 None 表示使用全局 max_tokens）。
structural_tag: Optional[str] = None
# 结构化标签，用于标记生成内容的特定结构（如 JSON、XML 等，默认 None）。
guided_json: Optional[Union[str, dict, BaseModel]] = None
# 引导生成符合 JSON 结构的内容，可以是 JSON 字符串、字典或 Pydantic 模型（默认 None）。
guided_regex: Optional[str] = None
# 引导生成符合正则表达式规则的内容（默认 None 表示不限制）。
guided_choice: Optional[List[str]] = None
# 引导生成内容从指定的候选列表中选择（默认 None 表示不限制）。
guided_grammar: Optional[str] = None
# 引导生成符合语法规则（如 BNF）的内容（默认 None 表示不限制）。
return_token_ids: Optional[bool] = None
# 是否返回生成结果的 token ID 而非文本（默认 None 表示返回文本）。
prompt_token_ids: Optional[List[int]] = None
# 直接传入 prompt 的 token ID 列表，跳过文本编码步骤（默认 None 表示使用文本输入）。
max_streaming_response_tokens: Optional[int] = None
# 流式输出时每次返回的最大 token 数（默认 None 表示不限制）。
disable_chat_template: Optional[bool] = False
# 是否禁用聊天模板渲染，直接使用原始输入（默认 False 表示启用模板）。
```
### 返回字段差异
@@ -110,16 +203,39 @@ FastDeploy 增加的返回字段如下：
返回参数总览：
```python
ChatCompletionResponse:
id: str
object: str = "chat.completion"
created: int = Field(default_factory=lambda: int(time.time()))
model: str
choices: List[ChatCompletionResponseChoice]
usage: UsageInfo
ChatCompletionResponseChoice:
index: int
message: ChatMessage
logprobs: Optional[LogProbs] = None
finish_reason: Optional[Literal["stop", "length", "tool_calls", "recover_stop"]]
ChatMessage:
role: str
content: str
reasoning_content: Optional[str] = None
prompt_token_ids: Optional[List[int]] = None
completion_token_ids: Optional[List[int]] = None
# 返回流式响应的字段
ChatCompletionStreamResponse:
id: str
object: str = "chat.completion.chunk"
created: int = Field(default_factory=lambda: int(time.time()))
model: str
choices: List[ChatCompletionResponseStreamChoice]
usage: Optional[UsageInfo] = None
ChatCompletionResponseStreamChoice:
index: int
delta: DeltaMessage
finish_reason: Optional[Literal["stop", "length"]] = None
logprobs: Optional[LogProbs] = None
finish_reason: Optional[Literal["stop", "length", "tool_calls"]] = None
arrival_time: Optional[float] = None
DeltaMessage:
role: Optional[str] = None
@@ -128,3 +244,155 @@ DeltaMessage:
completion_token_ids: Optional[List[int]] = None
reasoning_content: Optional[str] = None
```
## Completion API
Completion API 接口主要用于续聊场景, 适应于用户自定义好上下文输入, 并希望模型仅输出续写内容的场景; 推理过程不会增加其他 `prompt`拼接。：
### 发送用户请求
使用 curl 命令发送用户请求示例如下：
```bash
curl -X POST "http://0.0.0.0:8188/v1/completions" \
-H "Content-Type: application/json" \
-d '{
"prompt": "以下是一篇关于深圳文心公园的500字游记和赏析："
}'
```
使用 Python 脚本发送用户请求示例如下：
```python
import openai
host = "0.0.0.0"
port = "8170"
client = openai.Client(base_url=f"http://{host}:{port}/v1", api_key="null")
response = client.completions.create(
model="default",
prompt="以下是一篇关于深圳文心公园的500字游记和赏析：",
stream=False,
)
print(response.choices[0].text)
```
关于 OpenAI 协议的说明可参考文档 [OpenAI Completion API](https://platform.openai.com/docs/api-reference/completions/create)。
### 兼容OpenAI 参数
```python
model: Optional[str] = "default"
# 指定使用的模型名称或版本，默认值为 `"default"`（可能指向基础模型）。
prompt: Union[List[int], List[List[int]], str, List[str]]
# 输入提示，支持多种格式：
# - `str`: 纯文本提示（如 `"Hello, how are you?"`）。
# - `List[str]`: 多段文本（如 `["User:", "Hello!", "Assistant:", "Hi!"]`）。
# - `List[int]`: 直接传入 token ID 列表（如 `[123, 456]`）。
# - `List[List[int]]`: 多段 token ID 列表（如 `[[123], [456, 789]]`）。
best_of: Optional[int] = None
# 生成 `best_of` 个候选结果，然后返回其中评分最高的一个（需配合 `n=1` 使用）。
frequency_penalty: Optional[float] = None
# 频率惩罚系数，降低重复生成相同 token 的概率（`>1.0` 抑制重复，`<1.0` 鼓励重复）。
logprobs: Optional[int] = None
# 返回每个生成 token 的对数概率（log probabilities），可指定返回的候选数量。
max_tokens: Optional[int] = None
# 生成的最大 token 数（包括输入和输出），默认无限制（受模型上下文窗口限制）。
presence_penalty: Optional[float] = None
# 存在惩罚系数，降低新主题（未出现过的话题）的生成概率（`>1.0` 抑制新话题，`<1.0` 鼓励新话题）。
```
### FastDeploy 增加额外参数
> 注：
使用 curl 命令发送请求时， 可以直接使用以下参数；
使用openai.Client 发送请求时，需要使用将以下参数放入 `extra_body` 参数中， 如：`extra_body={"chat_template_kwargs": {"enable_thinking":True}, "include_stop_str_in_output": True}`。
额外采样参数的支持如下：
```python
top_k: Optional[int] = None
# 限制每一步生成时只考虑概率最高的 K 个 token，用于控制随机性（默认 None 表示不限制）。
min_p: Optional[float] = None
# 核采样（nucleus sampling）阈值，只保留概率累计超过 min_p 的 token（默认 None 表示禁用）。
min_tokens: Optional[int] = None
# 强制生成的最小 token 数，避免过早截断（默认 None 表示不限制）。
include_stop_str_in_output: Optional[bool] = False
# 是否在输出中包含停止符（stop string）的内容（默认 False，即遇到停止符时截断输出）。
bad_words: Optional[List[str]] = None
# 禁止生成的词汇列表（例如敏感词），模型会避免输出这些词（默认 None 表示不限制）。
repetition_penalty: Optional[float] = None
# 重复惩罚系数，降低已生成 token 的重复概率（>1.0 抑制重复，<1.0 鼓励重复，默认 None 表示禁用）。
```
其他参数的支持如下：
```python
guided_json: Optional[Union[str, dict, BaseModel]] = None
# 引导生成符合 JSON 结构的内容，可以是 JSON 字符串、字典或 Pydantic 模型（默认 None）。
guided_regex: Optional[str] = None
# 引导生成符合正则表达式规则的内容（默认 None 表示不限制）。
guided_choice: Optional[List[str]] = None
# 引导生成内容从指定的候选列表中选择（默认 None 表示不限制）。
guided_grammar: Optional[str] = None
# 引导生成符合语法规则（如 BNF）的内容（默认 None 表示不限制）。
return_token_ids: Optional[bool] = None
# 是否返回生成结果的 token ID 而非文本（默认 None 表示返回文本）。
prompt_token_ids: Optional[List[int]] = None
# 直接传入 prompt 的 token ID 列表，跳过文本编码步骤（默认 None 表示使用文本输入）。
max_streaming_response_tokens: Optional[int] = None
# 流式输出时每次返回的最大 token 数（默认 None 表示不限制）。
```
### 返回参数总览
```python
CompletionResponse:
id: str
object: str = "text_completion"
created: int = Field(default_factory=lambda: int(time.time()))
model: str
choices: List[CompletionResponseChoice]
usage: UsageInfo
CompletionResponseChoice:
index: int
text: str
prompt_token_ids: Optional[List[int]] = None
completion_token_ids: Optional[List[int]] = None
arrival_time: Optional[float] = None
logprobs: Optional[int] = None
reasoning_content: Optional[str] = None
finish_reason: Optional[Literal["stop", "length", "tool_calls"]]
# 返回流式响应的字段
CompletionStreamResponse：
id: str
object: str = "text_completion"
created: int = Field(default_factory=lambda: int(time.time()))
model: str
choices: List[CompletionResponseStreamChoice]
usage: Optional[UsageInfo] = None
CompletionResponseStreamChoice:
index: int
text: str
arrival_time: float = None
prompt_token_ids: Optional[List[int]] = None
completion_token_ids: Optional[List[int]] = None
logprobs: Optional[float] = None
reasoning_content: Optional[str] = None
finish_reason: Optional[Literal["stop", "length", "tool_calls"]] = None
```