---
title: v1/completions接口
description: "提供文本/流式推理处理功能。"
url: https://www.hiascend.com/document/detail/zh/mindie/latest/mindiellm/llmdev/mindie_llm0028.html
sourcePath: /source/zh/mindie/310/mindiellm/llmdev/mindie_llm0028.html
indexId: d488bfcda4ee3003f1339f8e8fbc3f2a9d00fb1e06402fe2736ebcae6f7d623b58
---
# v1/completions接口

#### 接口功能

提供文本/流式推理处理功能。


#### 接口格式

操作类型：POST

URL：https://{ip}:{port}/v1/completions

{ip}和{port}请使用业务面的IP地址和端口号，即“ipAddress”和“port”。


#### 请求参数

| 参数 | 是否必选 | 说明 | 取值要求 |
| --- | --- | --- | --- |
| model | 必选 | 模型名称。 | string类型；与Server配置文件中modelName的取值保持一致。 |
| prompt | 必选 | 推理请求内容。 | string：非空，0KB<字符数<=4MB，支持中英文。prompt经过tokenizer之后的token数量小于或等于maxInputTokenLen、maxSeqLen\-1、max\_position\_embeddings和1MB之间的最小值。其中，max\_position\_embeddings从权重文件config.json中获取，其他相关参数从配置文件中获取。 |
| use\_beam\_search | 可选 | 是否启用beam search搜索方式。 | bool类型，默认false；该参数不支持与stop参数叠加使用。 非流式： 返回参数n个序列，当n为null时，则返回一条回答。 流式： 假流式，生成的序列会放至choices数组中。 返回参数n个序列，当n为null时，则返回一条回答。 该参数不支持与MTP、并行解码、PD分离等特性叠加使用。 该参数不支持DeepSeek系列模型。 |
| best\_of | 可选 | 不开启beam search时，返回best\_of个序列 | 该参数后续版本即将下线。 int类型，取值范围为[1, 128]或null，默认值为1。当设置best\_of>1时，temperature的值必须设置为大于0。 当use\_beam\_search参数取值为false、null或不设置时： 非流式推理场景下，best\_of和n同时设置时，best\_of的取值必须大于等于n； 流式推理场景下，best\_of和n必须相等且不可单独设置best\_of。 当use\_beam\_search参数取值为true时，将不会对best\_of的取值进行校验。 该参数不支持与MTP、并行解码、PD分离等特性叠加使用。 该参数不支持DeepSeek系列模型。 |
| n | 可选 | 当best\_of配置为null或者不设置，或开启beam search时，返回n个序列。 | int类型，取值范围为[1, 8192]或null，默认值为1。当设置n>1时，temperature的值必须设置为大于0。 当use\_beam\_search参数取值为false、null或不设置时： 非流式推理场景下，n和best\_of同时设置时，best\_of的取值必须大于等于n； 流式推理场景下，n和best\_of必须相等且不可单独设置best\_of。 当use\_beam\_search参数取值为true时，将不会对best\_of的取值进行校验。 该参数不支持与MTP、并行解码、PD分离等特性叠加使用。 该参数不支持DeepSeek系列模型。 |
| logprobs | 可选 | 推理结果中每个token携带的logprobs的数量。 | int类型，取值范围为[0, 5]，默认为null。 该参数不支持与SplitFuse、Prefix Cache、并行解码、PD分离等特性叠加使用。 |
| max\_tokens | 可选 | 允许推理生成的最大token个数。实际产生的token数量同时受到配置文件maxIterTimes参数影响，推理token个数小于或等于Min(maxIterTimes, max\_tokens)。 | int类型，取值范围(0，2147483647]，默认值为Server配置文件中的maxIterTimes参数。 |
| seed | 可选 | 用于指定推理过程的随机种子，相同的seed值可以确保推理结果的可重现性，不同的seed值会提升推理结果的随机性。 | uint64\_t类型，取值范围(0, 18446744073709551615]，不传递该参数，系统会产生一个随机seed值。 当seed取到临近最大值时，会有WARNING，但并不会影响使用。若想去掉WARNING，可以减小seed取值。 |
| stop | 可选 | 停止推理的文本。输出结果中默认不包含停止词列表文本。 | List[string]类型或者string类型；默认为null。 List[string]：每个元素字符长度大于或等于1，列表元素总字符长度不超过32768（32\*1024）。列表为空时相当于null。 string：字符长度范围为1~32768。 该参数不支持与Function Call特性叠加使用，且不支持思维链内容解析。 |
| stop\_token\_ids | 可选 | 停止推理的token id列表。输出结果中默认不包含停止推理列表中的token id。 | List[int32]类型，超出int32的元素将会被忽略。 默认为null。 该参数不支持与Function Call特性叠加使用。 |
| include\_stop\_str\_in\_output | 可选 | 决定是否在生成的推理文本中包含停止字符串。 | bool类型，默认值为false。 true：包含停止字符串。 false：不包含停止字符串。 不传入stop或stop\_token\_ids时，此字段会被忽略。 该参数不支持与Function Call特性叠加使用，且不支持思维链内容解析。 |
| stream | 可选 | 指定返回结果是文本推理还是流式推理。 | bool类型，默认值false。 true：流式推理。 false：文本推理。 |
| repetition\_penalty | 可选 | 重复惩罚用于减少在文本生成过程中出现重复片段的概率。它对之前已经生成的文本进行惩罚，使得模型更倾向于选择新的、不重复的内容。 不建议同时修改该值与presence\_penalty或frequency\_penalty。 | float类型，取值范围(0.0, 2.0]，默认值1.0。 小于1.0表示对重复进行奖励。 1.0表示不进行重复度惩罚。 大于1.0表示对重复进行惩罚。 |
| presence\_penalty | 可选 | 存在惩罚介于\-2.0和2.0之间，它影响模型如何根据到目前为止是否出现在文本中来惩罚新token。正值将通过惩罚已经使用的词，增加模型谈论新主题的可能性。 不建议同时修改该值与repetition\_penalty或frequency\_penalty。 | float类型，取值范围[\-2.0, 2.0]，默认值0.0。 |
| frequency\_penalty | 可选 | 频率惩罚介于\-2.0和2.0之间，它影响模型如何根据文本中词汇的现有频率惩罚新词汇。正值将通过惩罚已经频繁使用的词来降低模型一行中重复用词的可能性。 不建议同时修改该值与repetition\_penalty或presence\_penalty。 | float类型，取值范围[\-2.0, 2.0]，默认值0.0。 |
| temperature | 可选 | 控制生成的随机性，较高的值会产生更多样化的输出。1.0表示不进行计算，大于1.0表示输出随机性提高。temperature=0.0，即采用greedy sampling。 | float类型，取值大于或等于0.0。 取0.0时将忽略其他后处理参数做greedy search。推荐使用大于或等于0.001的值，小于0.001可能会导致文本质量不佳。建议最大值取2.0，同时视模型而定。 |
| top\_p | 可选 | 控制模型生成过程中考虑的词汇范围，使用累计概率选择候选词，直到累积概率超过给定的阈值。该参数也可以控制生成结果的多样性，它基于累积概率选择候选词，直到累积概率超过给定的阈值为止。 | float类型，取值范围(1e\-6, 1.0]，默认值1.0。 |
| top\_k | 可选 | 控制模型生成过程中考虑的词汇范围，只从概率最高的k个候选词中选择。 | uint32\_t类型，取值范围\-1或者(0, 2147483647]。 字段未设置时，默认值由后端模型确定： atb（ATB Models）：配置文件为generation\_config.json文件与config.json文件，其中generation\_config.json的优先级更高。若用户与模型权重均未指定“top\_k”参数，为平衡性能与推理效果，“top\_k”参数将会被设定为1000。 ms（MindSpore）：配置文件为“.yaml”结尾的文件。若用户与模型权重均未指定“top\_k”参数，“top\_k”参数将会被设定为0。 字段设置的取值大于或等于vocabSize时，默认值为vocabSize。vocabSize是从modelWeightPath路径下的config.json文件中读取的vocab\_size或者padded\_vocab\_size的值，若不存在则vocabSize取默认值0。建议用户在config.json文件中添加vocab\_size或者padded\_vocab\_size参数，否则可能导致推理失败。 |
| ignore\_eos | 可选 | 指定在推理文本生成过程中是否忽略eos\_token结束符 | bool类型，默认值为false。 true：忽略eos\_token结束符。 false：不忽略eos\_token结束符。 |
| skip\_special\_tokens | 可选 | 指定在推理生成的文本中是否跳过特殊tokens。 | bool类型，默认值为true。 true：跳过特殊tokens。 false：保留特殊tokens。 |


#### 使用样例

请求样例：

```
POST https://
{ip}:{port}
/v1/completions
```

请求消息体：

- 流式推理：

```
{
"model": "Qwen2.5-7B-Instruct",
"prompt": "who are you",
"temperature": 1,
"max_tokens": 5,
"use_beam_search": true,
"ignore_eos":true,
"n": 2,
"best_of":2,
"stream": true,
"logprobs": 2}
```


- 文本推理：

```
{
"model": "llama3-70b",
"prompt": "who are you",
"temperature": 1,
"max_tokens": 5,
"ignore_eos":true,
"n": 2,
"best_of":2,
"stream": false,
"logprobs": 2}
```


响应样例：

- 流式推理：

```
data: {"id":"endpoint_common_1","object":"text_completion","created":1744948803,"model":"Qwen2.5-7B-Instruct","choices":[{"index":0,"text":"\nI am a large","logprobs":{"text_offset":[0,1,2,5,7],"token_logprobs":[-1.8828125,-0.018310546875,-0.054931640625,-0.435546875,-0.0286865234375],"tokens":["\n","I"," am"," a"," large"],"top_logprobs":[{"\n":-1.8828125,"\n\n":-2.0},{"I":-0.018310546875,"Hello":-4.53125},{" am":-0.054931640625,"'m":-2.9375},{" a":-0.435546875," Q":-1.1875},{" large":-0.0286865234375," language":-4.78125}]},"stop_reason":null,"finish_reason":"length"},{"index":1,"text":"\n\nI am a large","logprobs":{"text_offset":[13,15,16,19,21],"token_logprobs":[-2.0,-0.031494140625,-0.0791015625,-0.5546875,-0.01092529296875],"tokens":["\n\n","I"," am"," a"," large"],"top_logprobs":[{"\n\n":-2.0,"\n":-1.8828125},{"I":-0.031494140625,"Hello":-4.28125},{" am":-0.0791015625,"'m":-2.578125},{" a":-0.5546875," Q":-1.0546875},{" large":-0.01092529296875," language":-6.375}]},"stop_reason":null,"finish_reason":"length"}],"usage":{"prompt_tokens":3,"prompt_tokens_details": {"cached_tokens": 0},"completion_tokens":10,"total_tokens":13,"batch_size":[1,1,1,1,1,1,1,1,1,1],"queue_wait_time":[5496,146,65,60,111,42,27,70,64,51]}}
data: [DONE]
```


- 文本推理：

```
{
"id": "endpoint_common_15",
"object": "text_completion",
"created": 1744039004,
"model": "llama3-70b",
"choices": [
{
"index": 0,
"text": "? who am I?",
"logprobs": {
"text_offset": [
0,
1,
5,
8,
10
],
"token_logprobs": [
-0.5524268746376038,
-4.017512321472168,
-2.58241868019104,
-1.5019290447235107,
-0.00024381271214224398
],
"tokens": [
"?",
" who",
" am",
" I",
"?"
],
"top_logprobs": [
{
"?": -0.5524268746376038,
"?"": -1.177426815032959
},
{
" who": -4.017512321472168,
"\")": -0.2675122320652008,
" I": -2.455012321472168
},
{
" am": -2.58241868019104,
" are": -0.08241859823465347
},
{
" I": -1.5019290447235107,
" i": -0.25192904472351074
},
{
"?": -0.00024381271214224398,
"?\n": -8.750244140625
}
]
},
"stop_reason": null,
"finish_reason": "length"
},
{
"index": 1,
"text": " to say that I am",
"logprobs": {
"text_offset": [
11,
14,
18,
23,
25
],
"token_logprobs": [
-3.052426815032959,
-2.0233054161071777,
-0.043789759278297424,
-0.5240938663482666,
-0.008345582522451878
],
"tokens": [
" to",
" say",
" that",
" I",
" am"
],
"top_logprobs": [
{
" to": -3.052426815032959,
"?": -0.5524268746376038,
"?"": -1.177426815032959
},
{
" say": -2.0233054161071777,
" judge": -0.14830546081066132
},
{
" that": -0.043789759278297424,
" what": -3.168789863586426
},
{
" I": -0.5240938663482666,
"?": -1.1490938663482666
},
{
" am": -0.008345582522451878,
" can": -5.320845603942871
}
]
},
"stop_reason": null,
"finish_reason": "length"
}
],
"usage": {
"prompt_tokens": 3,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens": 10,
"total_tokens": 13,
"batch_size":[1,1,1,1,1,1,1,1,1,1],
"queue_wait_time":[5201,96,43,35,46,56,59,60,53,54]
}
}
```


#### 输出说明

| 返回值 | 返回值 | 返回值 | 类型 | 说明 |
| --- | --- | --- | --- | --- |
| id | id | id | string | 请求ID。 |
| object | object | object | string | 表示返回对象的类型，通常是text\_completion，表示这是一个文本生成的结果。 |
| created | created | created | int | 生成文本的时间戳，单位为秒。 |
| model | model | model | string | 使用的模型推理名称。 |
| choices | choices | choices | array | 推理结果列表。 |
| \- | index | index | int | 每个选择的索引，表示该选择在列表中的位置（从0开始）。 |
| \- | text | text | string | 模型生成的文本内容。 |
| \- | logprobs | logprobs | object | 包含有关该选择的详细logprobs信息。 |
| \- | \- | text\_offset | list(int[]) | 表示生成文本的位置偏移量。 |
| \- | \- | token\_logprobs | list(float[]) | 对应生成文本中每个token的对数概率值。 |
| \- | \- | tokens | list(string[]) | 生成的token。 |
| \- | \- | top\_logprobs | list(object[]) | 每个token的可能性，通常表示生成文本的最可能token和对应的logprobs。 |
| usage | usage | usage | object | 包含了有关请求中使用的令牌（tokens）的统计信息。令牌是模型输入和输出的基本单元。 |
| \- | prompt\_tokens | prompt\_tokens | int | 输入文本（提示语）所使用的令牌数量。 |
| \- | prompt\_tokens\_details | prompt\_tokens\_details | object | 输入文本（提示语）所使用的令牌细节信息。 |
| \- | \- | cached\_tokens | int | 输入文本（提示语）在推理过程中命中的缓存令牌数量。 仅在开启Prefix Cache特性时该字段有值； 不开启Prefix Cache特性时，该字段输出默认值0。 |
| \- | completion\_tokens | completion\_tokens | int | 模型生成的文本（响应）的令牌数量。 |
| \- | completion\_tokens\_details | completion\_tokens\_details | object | 模型生成的文本（响应）的令牌细节信息。 |
| \- | \- | reasoning\_tokens | int | 思维链内容对应的令牌数量。 仅在调用支持深度思考的模型时生成该字段，支持的模型请参见《MindIE LLM开发指南》中的“特性介绍 > 交互特性 > 思考解析”章节中的“限制与约束”。 |
| \- | total\_tokens | total\_tokens | int | 请求中总共使用的令牌数量（prompt\_tokens + completion\_tokens）。 |
| \- | batch\_size | batch\_size | list | 推理生成每个token时的batch size，数组长度为生成序列的token数量。 当同时生成多个序列的情况下，为所有序列共同的batch size，数组长度为最长序列的token数量。（每个batch size为当前轮次所有序列的batch size） |
| \- | queue\_wait\_time | queue\_wait\_time | list | 推理生成每个token时的队列等待时间，单位：us。数组长度为生成序列的token数量。 当同时生成多个序列的情况下，为所有序列共同的队列等待时延，数组长度为最长序列的token数量。（每个队列等待时间为当前轮次所有序列的队列等待时间） |
| stop\_reason | stop\_reason | stop\_reason | string | 表示生成停止的原因。为null表示没有显式的停止原因。 |
| finish\_reason | finish\_reason | finish\_reason | string | 表示生成停止的原因，常见值为length（因为生成达到了最大长度）或stop（遇到停止符号）。 |