# 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 (opens new window)

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

# 2.3. 接口要求

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

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

# 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信息，点击申请 (opens new window)	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引擎错误码查看对应的说明及处理策略

在这篇文章中：