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

文本/流式推理接口

接口功能

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

接口格式

操作类型：POST

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

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

请求参数

参数

是否必选

说明

取值要求

inputs

必选

推理请求内容。单模态文本模型为string类型，多模态模型为list类型。
  • string：非空，0KB<字符数<=4MB，支持中英文。prompt经过tokenizer之后的token数量小于或等于maxInputTokenLen、maxSeqLen-1、max_position_embeddings和1MB之间的最小值。其中，max_position_embeddings从权重文件config.json中获取，其他相关参数从配置文件中获取。
  • list：请参见使用样例中多模态模型样例。

-

type

可选

推理请求内容类型。
  • text：文本
  • image_url：图片
  • video_url：视频
  • audio_url：音频

单个请求中image_url、video_url、audio_url数量总和<=20个。

text

可选

推理请求内容为文本。

非空，支持中英文。

image_url

可选

推理请求内容为图片。

支持服务器本地路径的图片传入，图片类型支持jpg、png、jpeg和base64编码的jpg图片，支持URL图片传入，支持HTTP和HTTPS协议。当前支持传入的图片最大为20MB。

video_url

可选

推理请求内容为视频。

支持服务器本地路径的视频传入，视频类型支持MP4、AVI、WMV，支持URL视频传入，支持HTTP和HTTPS协议。当前支持传入的视频最大为512MB。

audio_url

可选

推理请求内容为音频。

支持服务器本地路径的音频传入，音频类型支持MP3、WAV、FLAC，支持URL音频传入，支持HTTP和HTTPS协议。当前支持传入的音频最大为20MB。

parameters

可选

模型推理后处理相关参数。

-

-

decoder_input_details

可选

是否返回推理请求文本的token ID。如果“stream”=true，该参数不能为true。

bool类型，默认值false。

details

可选

是否返回推理详细输出结果。根据TGI 0.9.4接口行为，“decoder_input_details”和“details”字段任意一个为true，即返回所有的details信息。

bool类型，默认值false。

do_sample

可选

是否做sampling。

bool类型，不传递该参数时，将由其他后处理参数决定是否做sampling。

  • true：做sampling。
  • false：不做sampling。

max_new_tokens

可选

允许推理生成的最大token个数。实际产生的token数量同时受到配置文件maxIterTimes参数影响，推理token个数小于或等于Min(maxIterTimes, max_new_tokens)。

int类型，取值范围(0，2147483647]，默认值20。

repetition_penalty

可选

重复惩罚用于减少在文本生成过程中出现重复片段的概率。它对之前已经生成的文本进行惩罚，使得模型更倾向于选择新的、不重复的内容。

float类型，大于0.0，默认值1.0。

  • 小于1.0表示对重复进行奖励。
  • 1.0表示不进行重复度惩罚。
  • 大于1.0表示对重复进行惩罚。

建议最大值取2.0，同时视模型而定。

return_full_text

可选

是否将推理请求文本（inputs参数）添加到推理结果前面。

bool类型，默认值false。

  • true：添加。
  • false：不添加。

seed

可选

用于指定推理过程的随机种子，相同的seed值可以确保推理结果的可重现性，不同的seed值会提升推理结果的随机性。

uint64_t，取值范围(0, 18446744073709551615]，不传递该参数，系统会产生一个随机seed值。

当seed取到临近最大值时，会有WARNING，但并不会影响使用。若想去掉WARNING，可以减小seed取值。

temperature

可选

控制生成的随机性，较高的值会产生更多样化的输出。

float类型，大于1e-6，默认值1.0。

取值越大，结果的随机性越大。推荐使用大于或等于0.001的值，小于0.001可能会导致文本质量不佳。

建议最大值取2.0，同时视模型而定。

top_k

可选

控制模型生成过程中考虑的词汇范围，只从概率最高的k个候选词中选择。

uint32_t类型，取值范围(0, 2147483647]，字段未设置时，默认值由后端模型确定，详情请参见《MindIE Motor开发指南》中的“服务化接口 > 说明”章节。取值大于或等于vocabSize时，默认值为vocabSize。

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

top_p

可选

控制模型生成过程中考虑的词汇范围，使用累计概率选择候选词，直到累积概率超过给定的阈值。该参数也可以控制生成结果的多样性，它基于累积概率选择候选词，直到累积概率超过给定的阈值为止。

float类型，取值范围(1e-6, 1.0)，字段未设置时，默认使用1.0来表示不进行该项处理，但是不可主动设置为1.0。

truncate

可选

输入文本做tokenizer之后，将token数量截断到该长度，读取截断后的n个token。若该字段值大于或等于token数量，则该字段无效。

uint32_t类型，取值范围(0, 2147483647]，字段未设置时，默认使用0来表示不进行该项处理，但是不可主动设置为0。

typical_p

可选

解码输出概率分布指数。

当前后处理不支持。

float类型，取值范围(0.0, 1.0]，默认值1.0。

watermark

可选

是否带模型水印。

当前后处理不支持。

bool类型，默认值false。

  • true：带模型水印。
  • false：不带模型水印。

stop

可选

停止推理的文本。输出结果默认不包含停止词列表文本。

List[string]类型或者string类型，默认值null。

  • List[string]：列表元素不超过1024个，每个元素的字符长度为1~1024，列表元素总字符长度不超过32768（256*128）。列表为空时相当于null。
  • string：字符长度范围为1~1024。

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

adapter_id

可选

指定推理时使用的LoRA权重，即LoRA ID。

string类型，默认值"None"。由字母、数字、点、中划线、下划线和正斜杠组成，字符串长度小于或等于256。

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

stream

可选

指定返回结果是文本推理还是流式推理。

bool类型，默认值false。

  • true：流式推理。
  • false：文本推理。

使用样例

请求样例：

POST https://{ip}:{port}/

请求消息体：

  • 单模态文本模型：
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    {
    "inputs": "My name is Olivier and I",
    "parameters": {
        "decoder_input_details": true,
        "details": true,
        "do_sample": true,
        "max_new_tokens": 20,
        "repetition_penalty": 1.03,
        "return_full_text": false,
        "seed": null,
        "temperature": 0.5,
        "top_k": 10,
        "top_p": 0.95,
        "truncate": null,
        "typical_p": 0.5,
        "watermark": false,
        "stop": ["stop1", "stop2"],
        "adapter_id": "None"
    },
    "stream": false
}
  • 多模态模型：

    "image_url"参数的取值请根据实际情况进行修改。

     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
    {
    "inputs": [
        {"type": "text", "text": "My name is Olivier and I"},
        {
            "type": "image_url",
            "image_url": "/xxxx/test.png"
        }
    ],
    "parameters": {
        "decoder_input_details": true,
        "details": true,
        "do_sample": true,
        "max_new_tokens": 20,
        "repetition_penalty": 1.03,
        "return_full_text": false,
        "seed": null,
        "temperature": 0.5,
        "top_k": 10,
        "top_p": 0.95,
        "truncate": null,
        "typical_p": 0.5,
        "watermark": false,
        "stop": ["stop1", "stop2"],
        "adapter_id": "None"
    },
    "stream": false
}

响应样例：

  • 文本推理（“stream”=false）：
      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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
    [
    {
        "details": {
            "prompt_tokens": 6,
            "finish_reason": "length",
            "generated_tokens": 20,
            "prefill": [
                {
                    "id": 5050,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 829,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 374,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 77018,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 323,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 358,
                    "logprob": null,
                    "special": null,
                    "text": null
                }
            ],
            "seed": 789070824,
            "tokens": [
                {
                    "id": 2776,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 264,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 3162,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 23576,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 504,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 9625,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 13,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 358,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 2948,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 311,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 1936,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 2513,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 11,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 5310,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 3482,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 8357,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 323,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 6371,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 10500,
                    "logprob": null,
                    "special": null,
                    "text": null
                },
                {
                    "id": 13,
                    "logprob": null,
                    "special": null,
                    "text": null
                }
            ]
        },
        "generated_text": "'m a software engineer from France. I love to build things, especially web applications and mobile apps."
    }
]
  • 流式推理：
    • 流式推理1（“stream”=true，“decoder_input_details”=false，使用sse格式返回）：
       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
      data: {"token":{"id":[29915],"text":"'","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[29885],"text":"m","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[263],"text":" a","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[5176],"text":" French","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[1410],"text":" gu","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[29891],"text":"y","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[1058],"text":" who","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[338],"text":" is","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[3063],"text":" looking","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[363],"text":" for","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[263],"text":" a","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[2058],"text":" place","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[304],"text":" to","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[5735],"text":" live","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[297],"text":" in","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[29889],"text":".","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[306],"text":" I","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[29915],"text":"'","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[29885],"text":"m","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[263],"text":" a","logprob":null,"special":null},"generated_text":"'m a French guy who is looking for a place to live in. I'm a","details":{"prompt_tokens":8,"finish_reason":"length","generated_tokens":20,"seed":218884523}}
    • 流式推理2（“stream”=true，“decoder_input_details”=false，配置项“fullTextEnabled”=true，使用sse格式返回）：
      1
2
3
4
5
6
7
8
9
      data: {"token":{"id":[11],"text":",","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[600],"text":", i","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[1184],"text":", i need","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[498],"text":", i need you","logprob":null,"special":null},"generated_text":null,"details":null}

data: {"token":{"id":[151645],"text":", i need you","logprob":null,"special":null},"generated_text":", i need you","details":{"prompt_tokens":1,"finish_reason":"eos_token","generated_tokens":5,"seed":1621189503}}

输出说明

表1 文本推理结果说明

返回值

类型

说明

details

object

推理details结果，请求参数“decoder_input_details”和“details”任意一个字段为true，即返回details结果。

-

prompt_tokens

int

用户输入的prompt文本对应的token长度。

finish_reason

string

结束原因。

  • eos_token：请求正常结束。
  • stop_sequence：
    • 请求被CANCEL或STOP，用户不感知，丢弃响应。
    • 请求执行中出错，响应输出为空，err_msg非空。
    • 请求输入校验异常，响应输出为空，err_msg非空。
  • length：
    • 请求因达到最大序列长度而结束，响应为最后一轮迭代输出。
    • 请求因达到最大输出长度（包括请求参数max_new_tokens；模型相关参数maxIterTimes、maxSeqLen和max_position_embeddings）而结束，响应为最后一轮迭代输出。
  • invalid flag：无效标记。

generated_tokens

int

推理结果token数量。PD场景下统计P和D推理结果的总token数量。当一个请求的推理长度上限取maxIterTimes的值时，D节点响应中generated_tokens数量为maxIterTimes+1，即增加了P推理结果的首token数量。

prefill

List[token]

请求参数“decoder_input_details”=true，返回推理请求文本detokenizer之后的token，默认为空列表。

-

id

int

token id。

logprob

float

对数概率，可以为空（第一个token概率值不能被计算获得）。

当前不支持，默认返回null。

special

bool

表明该token是否是special，如果是“special”=true，该token在做连接的时候可以被忽略。

当前不支持，默认返回null。

text

string

token对应文本。

当前不支持，默认返回null。

seed

int

返回推理请求的seed值，如果请求参数没有指定seed参数，则返回系统随机生成的seed值。

tokens

List[token]

返回推理结果的所有tokens。

-

id

int

token id。

logprob

对数概率

当前不支持，默认返回null。

special

bool

表明该token是否是special，如果是“special”=true，该token在做连接的时候可以被忽略。

当前不支持，默认返回null。

text

string

token对应文本。

当前不支持，默认返回null。

generated_text

string

推理返回结果。
表2 流式推理结果说明

返回值

类型

说明

data

object

一次推理返回的结果。

-

token

object

每一次推理的token。

-

id

list

生成的token id组成的列表。

text

string

token对应文本。

logprob

对数概率

当前不支持，默认返回null。

special

bool

表明该token是否是special，如果是“special”=true，该token在做连接的时候可以被忽略。当前不支持，默认返回null。

generated_text

string

推理文本返回结果，只在最后一次推理结果才返回。

details

object

推理details结果，只在最后一次推理结果返回，并且请求参数“details”=true才返回details结果。

-

prompt_tokens

int

用户输入的prompt文本对应的token长度。

finish_reason

string

结束原因。

  • eos_token：请求正常结束。
  • stop_sequence：
    • 请求被CANCEL或STOP，用户不感知，丢弃响应。
    • 请求执行中出错，响应输出为空，err_msg非空。
    • 请求输入校验异常，响应输出为空，err_msg非空。
  • length：
    • 请求因达到最大序列长度而结束，响应为最后一轮迭代输出。
    • 请求因达到最大输出长度（包括请求参数max_new_tokens；模型相关参数maxIterTimes、maxSeqLen和max_position_embeddings）而结束，响应为最后一轮迭代输出。
  • invalid flag：无效标记。

generated_tokens

int

推理结果token数量。PD场景下统计P和D推理结果的总token数量。当一个请求的推理长度上限取maxIterTimes的值时，D节点响应中generated_tokens数量为maxIterTimes+1，即增加了P推理结果的首token数量。

seed

int

返回推理请求的seed值，如果请求参数没有指定seed参数，则返回系统随机生成的seed值。