llm embedding 协议

1. llmembedding描述

大模型 embedding 能力

2. 接口说明

2.1. 请求方法和URL

POST http(s)://emb-cn-huabei-1.xf-yun.com/

注：全链路请求会话时长不超过1分钟

2.2. 接口Demo

embedding Python demo

demo 覆盖部分语言，其他语言参照下方接口文档进行开发。

2.3. 接口要求

接口类型：非流式 [http(s)]

接口鉴权：使用签名机制进行鉴权，签名详情参照 “接口鉴权 ”

3. 请求

3.1. 请求协议示例

{
    "header": {
        "app_id": appid,
        "uid": "39769795890",
        "status": 3,
    },
    "parameter": {
        "emb": {
        		"domain": "query" # 可选值：query 和para
            "feature": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "plain"
            }
        }
    },
    "payload": {
        "messages": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "json",
            "status": 3,
            "text": ""
        }
    }
}

协议结构说明

字段 含义 类型 说明
header 协议头部 Object 协议头部，用于描述平台特性的参数，详见 3.2.1 平台参数。
parameter 能力参数 Object AI 特性参数，用于控制 AI 引擎特性的开关。
emb 服务别名 Object
feature 响应数据控制 Object 数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系。
payload 输入数据段 Object 数据段，携带请求的数据。
messages 输入数据 Object 输入数据，详见 3.2.3 请求数据。

3.2. 请求参数

3.2.1. 平台参数

字段 含义 类型 限制 是否必传
app_id 在平台申请的app id信息，点击申请 string "maxLength":50 是
uid 请求用户服务返回的uid，用户及设备级别个性化功能依赖此参数 string "maxLength":50 否
status 请求状态，可选值为：3-一次传完 int 3 是

3.2.2. 服务特性参数

特性参数

特性标识 特性描述 数据类型
domain=query 用户问题向量化 string
domain=para 知识原文向量化 string

feature 段的参数（默认返回）

字段 含义 数据类型 取值范围 默认值 说明 必填
encoding 文本编码 string utf8, gb2312, gbk utf8 取值范围可枚举 否
compress 文本压缩格式 string raw, gzip raw 取值范围可枚举 否
format 文本格式 string plain, json, xml plain 取值范围可枚举 否

3.2.3. 请求数据

messages（默认请求）

字段 含义 数据类型 取值范围 默认值 说明 必填
encoding 文本编码 string utf8, gb2312, gbk utf8 取值范围可枚举 否
compress 文本压缩格式 string raw, gzip raw 取值范围可枚举 否
format 文本格式 string plain, json, xml json 取值范围可枚举 否
status 数据状态 int 3:一次性传完 3 取值范围为：3（一次传完） 否
text 文本数据 string 最小尺寸:1B, 最大尺寸:2K 需base64编码 是

3.3. 请求数据解析

text示例：

{
    "messages": [
        {
            "content": null,
            "role": null
        }
    ]
}

解析：

字段 含义 数据类型 取值范围 默认值 说明
messages.content 待向量化的数据 string -- null --
messages.role 角色 string user user --

4. 响应

4.1. 响应协议示例

{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802"
    },
    "payload": {
        "feature": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "text": ""
        }
    }
}

协议结构说明

字段 含义 类型 说明
header 协议头部 Object 协议头部，用于描述平台特性的参数，详见 4.2.1 平台参数。
payload 响应数据块 Object 数据段，携带响应的数据。
feature 响应数据块 Object 输出数据，详见 4.2.2 响应数据参数。

4.2. 响应参数

4.2.1. 平台参数

字段 含义 类型 是否必选
code 返回码，0表示成功，其它表示异常 int 是
message 错误描述 string 是
sid 本次会话的id string 是

4.2.2. 响应数据参数

feature（默认返回）

字段 含义 数据类型 取值范围 默认值 说明 必填
encoding 文本编码 string utf8, gb2312, gbk utf8 取值范围可枚举 否
compress 文本压缩格式 string raw, gzip raw 取值范围可枚举 否
format 文本格式 string plain, json, xml plain 取值范围可枚举 否
text 二进制数据 base64编码过的数据，需解密 需要将该数据转换为2560维的数组 base64编码 是

5. 错误码列表

错误码示例：

{
    "header": {
        "code": 11200, // 平台通用错误码，详细信息请参照 5.1 平台通用错误码
        "message": "licc failed", //错误原因描述
        "sid": "emb000e2143@dx18e79d7b6f26f19882"  //本次会话id，如需排查问题，请提供该会话给官方支持人员
    }
}

5.1. 平台通用错误码

错误码 错误描述 说明 处理策略
10009 input invalid data 输入数据非法 检查输入数据
10010 service license not enough 没有授权许可或授权数已满 提交工单
10019 service read buffer timeout, session timeout session超时 检查是否数据发送完毕但未关闭连接
10043 Syscall AudioCodingDecode error 音频解码失败 检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致
10114 session timeout session 超时 会话时间超时，检查是否发送数据时间超过了60s
10139 invalid param 参数错误 检查参数是否正确
10160 parse request json error 请求数据格式非法 检查请求数据是否是合法的json
10161 parse base64 string error base64解码失败 检查发送的数据是否使用base64编码了
10163 param validate error:... 参数校验失败 具体原因见详细的描述
10200 read data timeout 读取数据超时 检查是否累计10s未发送数据并且未关闭连接
10222 context deadline exceeded 1.上传的数据超过了接口上限； 2.SSL证书无效； 1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit；
10223 RemoteLB: can't find valued addr lb 找不到节点 提交工单
10313 invalid appid appid和apikey不匹配 检查appid是否合法
10317 invalid version 版本非法 请到控制台提交工单联系技术人员
10700 not authority 引擎异常 按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。
11200 auth no license 功能未授权 请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。
11201 auth no enough license 该APPID的每日交互次数超过限制 根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。
11503 server error :atmos return an error data 服务内部响应数据错误 提交工单
11502 server error: too many datas in resp 服务配置错误 提交工单
100001~100010 WrapperInitErr 调用引擎时出现错误 请根据message中包含的errno前往 5.2引擎错误码 查看对应的说明及处理策略