# 兼容 OpenAI 协议的服务化部署

FastDeploy 提供与 OpenAI 协议兼容的服务化部署方案。用户可以通过如下命令快速进行部署：

```bash
python -m fastdeploy.entrypoints.openai.api_server \
       --model baidu/ERNIE-4.5-0.3B-Paddle \
       --port 8188 --tensor-parallel-size 8 \
       --max-model-len 32768
```

如果要启用输出token的logprob，用户可以通过如下命令快速进行部署：

```bash
python -m fastdeploy.entrypoints.openai.api_server \
       --model baidu/ERNIE-4.5-0.3B-Paddle \
       --port 8188 --tensor-parallel-size 8 \
       --max-model-len 32768 \
       --enable-logprob
```

服务部署时的命令行更多使用方式参考[参数说明](../parameters.md)。

## Chat Completion API
FastDeploy 接口兼容 OpenAI 的 Chat Completion API，用户可以通过 OpenAI 协议发送用户请求。

### 发送用户请求

使用 curl 命令发送用户请求示例如下：

```bash
curl -X POST "http://0.0.0.0:8188/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {"role": "user", "content": "Hello!"}
  ]
}'
```

使用 curl 命令示例，演示如何在用户请求中包含logprobs参数：

```bash
curl -X POST "http://0.0.0.0:8188/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "logprobs": true, "top_logprobs": 0,
}'
```

使用 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.chat.completions.create(
    model="null",
    messages=[
        {"role": "system", "content": "I'm a helpful AI assistant."},
        {"role": "user", "content": "把李白的静夜思改写为现代诗"},
    ],
    stream=True,
)
for chunk in response:
    if chunk.choices[0].delta:
        print(chunk.choices[0].delta.content, end='')
print('\n')
```

关于 OpenAI 协议的说明可参考文档 [OpenAI Chat Completion API](https://platform.openai.com/docs/api-reference/chat/create)。

### 兼容OpenAI 参数
```python
messages: Union[List[Any], List[int]]
# 输入消息列表，可以是文本消息（`List[Any]`，通常为 `List[dict]`）或 token ID 列表（`List[int]`）。

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 表示不限制）。

bad_words_token_ids: Optional[List[int]] = None
# 禁止生成的token id列表，模型会避免输出这些词（默认 None 表示不限制）。

repetition_penalty: Optional[float] = None
# 重复惩罚系数，降低已生成 token 的重复概率（>1.0 抑制重复，<1.0 鼓励重复，默认 None 表示禁用）。
```
其他参数的支持如下：
```python
chat_template_kwargs: Optional[dict] = None
# 传递给聊天模板（chat template）的额外参数，用于自定义对话格式（默认 None）。

chat_template: Optional[str] = None
# 自定义聊天模板，会覆盖模型默认的聊天模板，（默认 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 表示使用文本输入）。

disable_chat_template: Optional[bool] = False
# 是否禁用聊天模板渲染，直接使用原始输入（默认 False 表示启用模板）。

temp_scaled_logprobs: Optional[bool] = False
# 计算logprob时是否对logits除以温度系数（默认 False 表示不除以温度系数）。

top_p_normalized_logprobs: Optional[bool] = False
# 计算logprob时是否进行 top_p 归一化（默认 False 表示不进行top_p归一化）。
```

### 返回字段差异

FastDeploy 增加的返回字段如下：

- `arrival_time`：返回所有 token 的累计耗时
- `reasoning_content`: 思考链的返回结果
- `prompt_token_ids`: 输入序列的 token id 列表
- `completion_token_ids`: 输出序列的 token id 列表

返回参数总览：

```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
    logprobs: Optional[LogProbs] = None
    finish_reason: Optional[Literal["stop", "length", "tool_calls"]] = None
    arrival_time: Optional[float] = None
DeltaMessage:
    role: Optional[str] = None
    content: Optional[str] = None
    prompt_token_ids: Optional[List[int]] = None
    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 表示使用文本输入）。

```

### 返回参数总览

```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

```