昇腾社区首页
中文
注册
开发者
下载
支持
积分兑换 NEW

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、SplitFuse、Prefix Cache、并行解码、PD分离等特性叠加使用。

该参数不支持DeepSeek系列模型。

n

可选

当best_of配置为null或者不设置，或开启beam search时，返回n个序列。

int类型，取值范围为[1, 128]或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、SplitFuse、Prefix Cache、并行解码、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。

PD分离场景暂不支持该参数。

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]，字段未设置时，默认值由后端模型确定，详情请参见《MindIE Motor开发指南》中的“服务化接口 > 说明”章节。取值大于或等于vocabSize时，默认值为vocabSize。

vocabSize是从modelWeightPath路径下的config.json文件中读取的vocab_size或者padded_vocab_size的值，若不存在则vocabSize取默认值0。建议用户在config.json文件中添加vocab_size或者padded_vocab_size参数，否则可能导致推理失败。

stop_token_ids

可选

停止推理的token id列表。输出结果中默认不包含停止推理列表中的token id。

List[int32]类型，超出int32的元素将会被忽略。

默认为null。

include_stop_str_in_output

可选

决定是否在生成的推理文本中包含停止字符串。

bool类型，默认值为false。PD分离场景暂不支持此参数。

  • true：包含停止字符串。
  • false：不包含停止字符串。

不传入stop或stop_token_ids时，此字段会被忽略。

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

请求消息体：

  • 流式推理：
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    {
    "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}
  • 文本推理：
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    {
    "model": "llama3-70b",
    "prompt": "who are you",
    "temperature": 1,
    "max_tokens": 5,
    "ignore_eos":true,
    "n": 2,
    "best_of":2,
    "stream": false,
    "logprobs": 2}

响应样例：

  • 流式推理：
    1
2
3
    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,"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]
  • 文本推理：
      1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
    {
    "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,
        "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

string

请求ID。

object

string

表示返回对象的类型，通常是text_completion，表示这是一个文本生成的结果。

created

int

生成文本的时间戳，单位为秒。

model

string

使用的模型推理名称。

choices

array

推理结果列表。

-

index

int

每个选择的索引，表示该选择在列表中的位置（从0开始）。

text

string

模型生成的文本内容。

logprobs

object

包含有关该选择的详细logprobs信息。

-

text_offset

list(int[])

表示生成文本的位置偏移量。

token_logprobs

list(float[])

对应生成文本中每个token的对数概率值。

tokens

list(string[])

生成的token。

top_logprobs

list(object[])

每个token的可能性，通常表示生成文本的最可能token和对应的logprobs。

usage

object

包含了有关请求中使用的令牌（tokens）的统计信息。令牌是模型输入和输出的基本单元。

-

prompt_tokens

int

输入文本（提示语）所使用的令牌数量。

completion_tokens

int

模型生成的文本（响应）的令牌数量。

total_tokens

int

请求中总共使用的令牌数量（prompt_tokens + completion_tokens）。

batch_size

list

推理生成每个token时的batch size，数组长度为生成序列的token数量。

当同时生成多个序列的情况下，为所有序列共同的batch size，数组长度为最长序列的token数量。（每个batch size为当前轮次所有序列的batch size）

queue_wait_time

list

推理生成每个token时的队列等待时间，单位：us。数组长度为生成序列的token数量。

当同时生成多个序列的情况下，为所有序列共同的队列等待时延，数组长度为最长序列的token数量。（每个队列等待时间为当前轮次所有序列的队列等待时间）

stop_reason

string

表示生成停止的原因。为null表示没有显式的停止原因。

finish_reason

string

表示生成停止的原因，常见值为length（因为生成达到了最大长度）或stop（遇到停止符号）。
父主题： 推理接口