文本/流式推理接口

接口功能

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

该接口即将下线，建议使用OpenAI接口。

接口格式

操作类型：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：音频多媒体文件使用说明： HTTP/HTTPS 访问方式：请先配置白名单环境变量ALLOWED_MEDIA_DOMAINS_ENV。示例如下（示例中的xxx.xxx.xxx.xxx需替换为资源加载的实际IP）： export ALLOWED_MEDIA_DOMAINS_ENV="upload.xxxmedia.org,cxxx.xxx.com,xxx.xxx.xxx.xxx" 本地文件方式：请将多媒体文件放置在以下目录： /data/multimodal_inputs/ 说明：安全风险提示：在使用前，请务必确保传入的多媒体文件来源可信、内容安全，避免潜在风险。避免解析至本地IP、内网IP，同时避免使用nip.io、sslip.io等可解析至任意IP的域名。在使用前，请确保磁盘空间足够以支持多媒体文件的下载。建议预留空间计算公式如下：单请求最大文件大小 × 最大并发数 × 1.5(预留系数) 例如：若单请求最大文件大小为 512MB，最大并发数为 1000，则应确保磁盘剩余空间大于750G。
	text	可选	推理请求内容为文本。	非空，支持中英文。
	image_url	可选	推理请求内容为图片。	支持服务器本地路径的图片传入，图片类型支持jpg、png、jpeg和base64编码的jpg图片，支持URL图片传入，支持HTTP和HTTPS协议。当前支持传入的图片最大为40MB。
	video_url	可选	推理请求内容为视频。	支持服务器本地路径的视频传入，视频类型支持MP4、AVI、WMV，支持URL视频传入，支持HTTP和HTTPS协议。当前支持传入的视频最大为512MB。
	audio_url	可选	推理请求内容为音频。	支持服务器本地路径的音频传入，音频类型支持MP3、WAV、FLAC，支持URL音频传入，支持HTTP和HTTPS协议。当前支持传入的音频最大为40MB。
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]。字段未设置时，默认值由后端模型确定： 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参数，否则可能导致推理失败。
	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}/

请求消息体：

单模态文本模型：

{
    "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"参数的取值请根据实际情况进行修改。

{
    "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）：

[
    {
        "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格式返回）：

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格式返回）：

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值。

父主题： 兼容TGI 0.9.4版本接口