--- title: 文本/流式推理接口 description: "提供文本/流式推理处理功能。" url: https://www.hiascend.com/document/detail/zh/mindie/latest/mindiellm/llmdev/mindie_llm0040.html sourcePath: /source/zh/mindie/310/mindiellm/llmdev/mindie_llm0040.html indexId: 77a95f80d82eb0f4d8964c9a012e38a2caff82a0dd6d8a6a016c57562ee387aa58 --- # 文本/流式推理接口 #### 接口功能 提供文本/流式推理处理功能。 该接口即将下线，建议使用OpenAI接口。 #### 接口格式 操作类型：POST URL：https://{ip}:{port}/infer {ip}和{port}请使用业务面的IP地址和端口号，即“ipAddress”和“port”。 #### 请求参数 | 参数名 | 参数名 | 是否必选 | 说明 | 取值要求 | | --- | --- | --- | --- | --- | | inputs | 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。 | | stream | stream | 可选 | 指定返回结果是文本推理还是流式推理。 | bool类型，默认值false。 true：流式推理。 false：文本推理。 | | parameters | parameters | 可选 | 模型推理后处理相关参数。 | \- | | \- | 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。 | | \- | max\_new\_tokens | 可选 | 允许推理生成的最大token个数。实际产生的token数量同时受到配置文件maxIterTimes参数影响，推理token个数小于或等于Min(maxIterTimes, max\_new\_tokens)。 | int类型，取值范围(0，2147483647]，默认值20。 | | \- | do\_sample | 可选 | 是否做sampling。 | bool类型，不传递该参数时，将由其他后处理参数决定是否做sampling。 true：做sampling。 false：不做sampling。 | | \- | seed | 可选 | 用于指定推理过程的随机种子，相同的seed值可以确保推理结果的可重现性，不同的seed值会提升推理结果的随机性。 | uint64\_t类型，取值范围(0, 18446744073709551615]，不传递该参数，系统会产生一个随机seed值。 当seed取到临近最大值时，会有WARNING，但并不会影响使用。若想去掉WARNING，可以减小seed取值。 | | \- | repetition\_penalty | 可选 | 重复惩罚用于减少在文本生成过程中出现重复片段的概率。它对之前已经生成的文本进行惩罚，使得模型更倾向于选择新的、不重复的内容。 | float类型，大于0.0，默认值1.0。 小于1.0表示对重复进行奖励。 1.0表示不进行重复度惩罚。 大于1.0表示对重复进行惩罚。 建议最大值取2.0，同时视模型而定。 | | \- | details | 可选 | 是否返回推理详细输出结果。 | bool类型，默认值false。 | | \- | typical\_p | 可选 | 解码输出概率分布指数。 当前后处理不支持。 | float类型，取值范围(0.0, 1.0]，默认值1.0。 | | \- | watermark | 可选 | 是否带模型水印。 当前后处理不支持。 | bool类型，默认值false。 true：带模型水印。 false：不带模型水印。 | | \- | priority | 可选 | 设置请求优先级。 | uint64\_t类型，取值范围[1, 5]，默认值5。 值越低优先级越高，最高优先级为1。 | | \- | timeout | 可选 | 设置等待时间，超时则断开请求。 | uint64\_t类型，取值范围(0, 3600]，默认值600，单位：秒。 | #### 使用样例 请求样例： ``` POST https:// {ip}:{port} /infer ``` 请求消息体： - 单模态文本模型： ``` { "inputs": "My name is Olivier and I", "stream": false, "parameters": { "temperature": 0.5, "top_k": 10, "top_p": 0.95, "max_new_tokens": 20, "do_sample": true, "seed": null, "repetition_penalty": 1.03, "details": true, "typical_p": 0.5, "watermark": false, "priority": 5, "timeout": 10 } } ``` - 多模态模型： "image_url"参数的取值请根据实际情况进行修改。 ``` { "inputs": [ {"type": "text", "text": "My name is Olivier and I"}, { "type": "image_url", "image_url": "/xxxx/test.png" } ], "stream": false, "parameters": { "temperature": 0.5, "top_k": 10, "top_p": 0.95, "max_new_tokens": 20, "do_sample": true, "seed": null, "repetition_penalty": 1.03, "details": true, "typical_p": 0.5, "watermark": false, "priority": 5, "timeout": 10 } } ``` 响应样例： - 文本推理（“stream”=false）： ``` { "generated_text": "am a French native speaker. I am looking for a job in the hospitality industry. I", "details": { "finish_reason": "length", "generated_tokens": 20, "seed": 846930886 } } ``` - 流式推理： - 流式推理1（“stream”=true，使用sse格式返回）： ``` data: {"prefill_time":45.54,"decode_time":null,"token":{"id":[626],"text":"am"}} data: {"prefill_time":null,"decode_time":128.32,"token":{"id":[263],"text":" a"}} data: {"prefill_time":null,"decode_time":18.17,"token":{"id":[5176],"text":" French"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[17739],"text":" photograph"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[261],"text":"er"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[2729],"text":" based"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[297],"text":" in"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[3681],"text":" Paris"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[29889],"text":"."}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[13],"text":"\n"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[29902],"text":"I"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[505],"text":" have"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[1063],"text":" been"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[27904],"text":" shooting"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[1951],"text":" since"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[306],"text":" I"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[471],"text":" was"}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[29871],"text":" "}} data: {"prefill_time":null,"decode_time":16.80,"token":{"id":[29896],"text":"1"}} data: {"prefill_time":null,"decode_time":16.80,"generated_text":"am a French photographer based in Paris.\nI have been shooting since I was 15","details":{"finish_reason":"length","generated_tokens":20,"seed":846930886},"token":{"id":[29945],"text":null}} ``` - 流式推理2（“stream”=true，配置项“fullTextEnabled”=true，使用sse格式返回）： ``` data: {"prefill_time":33.55400085449219,"decode_time":null,"token":{"id":[5122],"text":":"}} data: {"prefill_time":null,"decode_time":19.922000885009766,"token":{"id":[7552],"text":":)"}} data: {"prefill_time":null,"decode_time":12.803999900817871,"token":{"id":[40],"text":":)I"}} data: {"prefill_time":null,"decode_time":11.869000434875488,"token":{"id":[2776],"text":":)I'm"}} data: {"prefill_time":null,"decode_time":12.008000373840332,"generated_text":":)I'm ","details":null,"token":{"id":[4102],"text":null}} ``` #### 输出说明 **表1 文本推理结果说明** | 返回值 | 返回值 | 类型 | 说明 | | --- | --- | --- | --- | | generated\_text | generated\_text | string | 推理返回结果。 | | details | details | object | 推理details结果。目前定义以下字段，支持扩展。 | | \- | 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 | 如果请求指定了sampling seed，返回该seed值。 | **表2 流式推理结果说明** | 返回值 | 返回值 | 返回值 | 类型 | 说明 | | --- | --- | --- | --- | --- | | data | data | data | object | 一次推理返回的结果。 | | \- | prefill\_time | prefill\_time | float | 流式推理下首token时延，单位：ms。 | | \- | decode\_time | decode\_time | float | 流式推理下非首token的token时延，单位：ms。 | | \- | generated\_text | generated\_text | string | 推理文本结果，只在最后一次推理结果才返回。 | | \- | details | details | object | 推理details结果，只在最后一次推理结果返回，支持扩展。 | | \- | \- | 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 | 如果请求指定了sampling seed，返回该seed值。 | | \- | token | token | List[token] | 每一次推理的token。 | | \- | \- | id | list | 生成的token id组成的列表。 | | \- | \- | text | string | token对应文本。 |