翻译大模型

# 翻译大模型Web API文档

## 1. 接口说明

Tips：
1. 计费包含接口的输入和输出内容
2. 1tokens 约等于1.5个中文汉字 或者 0.8个英文单词

### 1.1 请求地址

**星火大模型请求地址**

```text
wss://spark-api-n.xf-yun.com/v1.1/chat_translate
```

### 1.2 接口鉴权

参考[通用URL鉴权文档](https://www.xfyun.cn/doc/spark/general_url_authentication.html)

### 1.3 接口请求

#### 1.3.1 请求参数

```text
# 参数构造示例如下
{
        "header": {
            "app_id": "12345",
            "uid": "12345"
        },
        "parameter": {
            "chat": {
                "request_type":0,
                "domain": "common",
                "from":"cn",
                "to":"en"
                "temperature": 0.5,
                "max_tokens": 1024, 
            }
        },
        "payload": {
            "message": {
                # 如果想获取结合上下文的回答，需要开发者每次将历史问答信息一起传给服务端，如下示例
                # 注意：text里面的所有content内容加一起的tokens需要控制在8192以内，开发者如有较长对话需求，需要适当裁剪历史信息
                
                # 详情参考下方text示例
                "text": {
                            "src": "轻轻的我⾛了，正如我轻轻地来"
                    }

}
    }
}
```
```text
# text示例
                # 常规单句翻译
                "text": {
                            "src": "轻轻的我⾛了，正如我轻轻地来"
                    }

# 常规对话翻译        
                "text": {
                            "src": "我的名字叫张三",
                            "trg_role": "A",
                            "conver_info": [
                                {
                                    "role": "A",
                                    "content": "你好"
                                },
                                {
                                    "role": "A",
                                    "content": "下午好"
                                },
                                {
                                    "role": "B",
                                    "content": "Good afternoon, nice to meet you."
                                },
                                {
                                    "role": "A",
                                    "content": "我也很⾼兴认识你，请问你叫什么名字？"
                                },
                                {
                                    "role": "B",
                                    "content": "My name is Derron, and you?"
                                }
                            ]
                    }

# 带有全局翻译⻛格约束的常规对话翻译
                "text": {
                            "src": "我也很期待最终的官⽅定价",
                            "trg_role": "A",
                            "history_info": [
                                {
                                    "role": "user",
                                    "content": "请结合新能源领域知识，接下来以⼝语化⻛格进⾏翻译，"
                                },
                                {
                                    "role": "assistant",
                                    "content": "好的，请提供待翻译的内容"
                                }
                            ],
                            "conver_info": [
                                {
                                    "role": "A",
                                    "content": "你知道雷军开始造⻋了吗"
                                },
                                {
                                    "role": "B",
                                    "content": "Yes,I know."
                                },
                                {
                                    "role": "A",
                                    "content": "你知道⼩米汽⻋的定价吗"
                                },
                                {
                                    "role": "B",
                                    "content": "As far as I know, it hasn't been announced yet"
                                }
                            ]
                        }

# 个性化单轮翻译（不含历史轮信息）
                "text": {
                            "src": "帮我翻译⼀下“轻轻的我⾛了，正如我轻轻地来”这句话"
                    }
                    
                # 个性化多轮翻译（含历史轮信息）        
                "text": {
                            "src": "⽤现在式重新翻⼀下",
                            "history_info": [
                                {
                                    "role": "user",
                                    "content": "帮我翻译⼀下“轻轻的我⾛了，正如我轻轻地来”"
                                },
                                {
                                    "role": "assistant",
                                    "content": "Gently I leave, just as I came gently."
                                }
                            ]
                        }
```
接口请求字段由三个部分组成：header，parameter, payload。 字段解释如下

**header部分**

| 参数名称 | 类型   | 必传 | 参数要求   | 参数说明                                    |
| -------- | ------ | ---- | ---------- | :------------------------------------------ |
| app_id   | string | 是   |            | 应用appid，从开放平台控制台创建的应用中获取 |
| uid      | string | 否   | 最大长度32 | 每个用户的id，用于区分不同用户              |

**parameter.chat部分**

| 参数名称    | 类型   | 必传 | 参数要求                                                     | 参数说明                                                     |
| ----------- | ------ | ---- | ------------------------------------------------------------ | :----------------------------------------------------------- |
| request_type      | int | 是   | 0:常规翻译场景, 1:个性化翻译场景              | 翻译场景区分	|
| from      | string | 否   | cn:中文, en:英文             | 源语种		|
| to      | string | 否   | cn:中文, en:英文              | 目标语种		|
| domain      | string | 否   | 取值为[common、law、finance、computer、energy、sports、medicine]              | 领域信息,多个领域英文分号隔开|
| temperature | float  | 否   | 取值范围 (0，1] ，默认值0.5                                  | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens  | int    | 否   | V1.5取值为[1,4096] V2.0、V3.0和V3.5取值为[1,8192]，默认为2048。 | 模型回答的tokens的最大长度                                   |
| top_k       | int    | 否   | 取值为[1，6],默认为4                                         | 从k个候选中随机选择⼀个（⾮等概率）                          |
| chat_id     | string | 否   | 需要保障用户下的唯一性                                       | 用于关联用户会话                                             |

**payload.message.text部分**

*注：text下所有content累计内容 tokens需要控制在8192内*

| 参数名称 | 类型   | 必传 | 参数要求                              | 参数说明                                                     |
| -------- | ------ | ---- | ------------------------------------- | ------------------------------------------------------------ |
| src  | string | 是   | 字符长度1 ~ 4194304的字符串| 	待翻译文本或个性化Prompt                                          |
| trg_role  | string | 否   | A: 角色AB: 角色B | 对话翻译中待翻译文本所属角色	常规对话翻译必填                                          |
| history_info  | array |  否  |  | 个性化多轮历史信息	                                           |
| history_info.role  | string |    | user: 提问assistant: 回答 | 角色                                       |
| history_info.content  | string |    | 	字符长度1 ~ 4194304的字符串 | 内容                                       |
| conver_info  | array | 否   |  | 个对话场景历史信息		                                           |
| conver_info.role  | string |    | 	A: 角色AB: 角色B | 角色                                       |
| conver_info.content  | string |    | 	字符长度1 ~ 4194304的字符串 | 对话内容	                                       |

### 1.4 接口响应

```text
# 接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示
{
    "header":{
        "code":0,
        "message":"Success",
        "sid":"cht000cb087@dx18793cd421fb894542",
        "status":2
    },
    "payload":{
        "choices":{
            "status":2,
            "seq":0,
            "text":[
                {
                    "content":"ASUVORK5CYII=", // 真实数据的base64编码
                    "role":"assistant",
                    "index":0
                }
            ]
        },
        "usage":{
            "text":{
                "question_tokens":4,
                "prompt_tokens":5,
                "completion_tokens":9,
                "total_tokens":14
            }
        }
    }
}
```
```text
# content示例
    # 常规单句翻译响应
    "content": {
        "respond_type": 0,
        "from": "cn",
        "to": "en",
        "trans_result": {
            "type": "SparkModel",
            "src": "轻轻的我⾛了，正如我轻轻地来",
            "dst": "I left gently, just as I arrived quietly.",
            "prompt": "你是⼀个翻译专家，擅⻓中英文翻译，请将下⾯这句中文翻译成英文：\n轻轻的我⾛了，正如我轻轻地来",
            "answer": "I left gently, just as I arrived quietly."
        }
    }

# 常规对话翻译响应
    "content":{
        "respond_type": 0,
        "from": "cn",
        "to": "en",
        "trans_result": {
            "type": "SparkModel",
            "src": "我的名字叫张三",
            "dst": "My name is ZhangSan.",
            "prompt": "你是⼀个翻译专家，擅⻓中英文翻译，下⾯是⼀段对话历史\n{A: 你好\n A:下午好\nB:Good afternoon, nice to meet you.\nA:我也很⾼兴认识你，请问你叫什么名字？\nB:My name is Derron, and you?\n请结合上下文语境信息，将下⾯这句A说的话从中文翻译成英文：\n我的名字叫张三\n",
            "answer": "My name is ZhangSan."
            
        }
    }

# 带有全局翻译⻛格约束的常规对话翻译
    "content":{
        "respond_type": 0,
        "from": "cn",
        "to": "en",
        "trans_result": {
            "type": "SparkModel",
            "src": "我也很期待最终的官⽅定价",
            "dst": "I'm also looking forward to the final official pricing",
            "prompt": :"你是⼀个翻译专家，擅⻓中英文翻译，下⾯是⼀段对话历史\n{A: 你知道雷军开始造⻋了吗\nB:Yes,I know.\nA:你知道⼩米汽⻋的定价吗\nB:As far as I know, it hasn't been announced ye\n请结合上下文语境信息，将下⾯这句A说的话从中文翻译成英文：\我也很期待最终的官⽅定价\n",
            "answer": "I'm also looking forward to the final official pricing"
        }
    }

# 个性化单轮翻译响应
    "content":{
        "respond_type": 1,
        "from": "",
        "to": "",
        "trans_result": {
            "type": "SparkModel",
            "src": "轻轻的我⾛了，正如我轻轻地来",
            "dst": "I left gently, just as I arrived quietly.",
            "prompt": "帮我翻译⼀下“轻轻的我⾛了，正如我轻轻地来”这句话",
            "answer": "#command#：\n xxx #source#：\n轻轻的我⾛了，正如我轻轻地来\n#translation#\n：I left gently, just as I arrived quietly."
        }
    }

# 个性化多轮翻译响应
    "content":{
        "respond_type": 1,
        "from": "cn",
        "to": "en",
        "trans_result": {
            "type": "SparkModel",
            "src": "轻轻的我⾛了，正如我轻轻地来",
            "dst": "Gently I am leaving, just as I came gently.",
            "prompt": "⽤现在式重新翻⼀下",
            "answer": "#source#：\n轻轻的我⾛了，正如我轻轻地来\n #translation#\n：GentlyI am leaving, just as I came gently."
        }
    }

```
4.1. 响应协议示例

接口返回字段分为两个部分，header，payload。字段解释如下

**header部分**

| 字段名  | 类型   | 字段说明                                                     |
| ------- | ------ | ------------------------------------------------------------ |
| code    | int    | 错误码，0表示正常，非0表示出错；详细释义可在接口说明文档最后的错误码说明了解 |
| message | string | 会话是否成功的描述信息                                       |
| sid     | string | 会话的唯一id，用于讯飞技术人员查询服务端会话日志使用,出现调用错误时建议留存该字段 |
| status  | int    | 会话状态，取值为[0,1,2]；0代表首次结果；1代表中间结果；2代表最后一个结果 |

**payload.choices部分**

| 字段名  | 类型   | 字段说明                                                     |
| ------- | ------ | ------------------------------------------------------------ |
| status  | int    | 文本响应状态，取值为[0,1,2]; 0代表首个文本结果；1代表中间文本结果；2代表最后一个文本结果 |
| seq     | int    | 返回的数据序号，取值为[0,9999999]                            |
| content | string | AI的回答内容                                                 |
| role    | string | 角色标识，固定为assistant，标识角色为AI                      |
| index   | int    | 结果序号，取值为[0,10]; 当前为保留字段，开发者可忽略         |

**payload.choices.text[idx].content部分**

| 字段名  | 类型   | 字段说明                                                     |
| ------- | ------ | ------------------------------------------------------------ |
| respond_type  | int    |响应类型	 0: 常规翻译1: 个性化翻译2: 预留字段 |
| from     | string    | 源语种	       cn: 中文en: 英文 个性化场景无语种信息                     |
| to     | string    | 目标语种		       cn: 中文en: 英文 个性化场景无语种信息                     |
| trans_result     | object    | 翻译结果                     |
| trans_result.type     | string    | 翻译结果类型 SparkModel: 来自星火大模型 TinyModel: 来自兜底小模型 Refuse: 拒翻             |
| trans_result.src     | string    | 待翻译原文 或 大模型重新润色或组织后原文             |
| trans_result.dst     | string    | 翻译结果	             |
| trans_result.prompt     | string    |引擎拼接后Prompt		             |
| trans_result.answer     | string    |大模型原始输出，内容将会解析至src和dst			             |

**payload.usage部分(在最后一次结果返回)**

| 字段名            | 类型 | 字段说明                                                     |
| ----------------- | ---- | ------------------------------------------------------------ |
| question_tokens   | int  | 保留字段，可忽略                                             |
| prompt_tokens     | int  | 包含历史问题的总tokens大小                                   |
| completion_tokens | int  | 回答的tokens大小                                             |
| total_tokens      | int  | prompt_tokens和completion_tokens的和，也是本次交互计费的tokens大小 |# N方向-翻译大模型接口文档

## 5. 错误码列表

| 错误码 | 错误信息                                                     |
| ------ | ------------------------------------------------------------ |
| 0      | 成功                                                         |
| 10000  | 升级为ws出现错误                                             |
| 10001  | 通过ws读取用户的消息 出错                                    |
| 10002  | 通过ws向用户发送消息 出错                                    |
| 10003  | 用户的消息格式有错误                                         |
| 10004  | 用户数据的schema错误                                         |
| 10005  | 用户参数值有错误                                             |
| 10006  | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。     |
| 10007  | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。<br />（必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008  | 服务容量不足，联系服务商                                     |
| 10009  | 和引擎建立连接失败                                           |
| 10010  | 接收引擎数据的错误                                           |
| 10011  | 向引擎发送数据的错误                                         |
| 10012  | 引擎内部错误                                                 |
| 10013  | 用户问题涉及敏感信息，审核不通过，拒绝处理此次请求。         |
| 10014  | 回复结果涉及到敏感信息，审核不通过，后续结果无法展示给用户。（建议清空当前结果，并给用户提示/警告：该答案涉及到敏感/政治/恐怖/色情/暴力等方面，不予显示/回复） |
| 10015  | appid在黑名单中                                              |
| 10016  | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权 等等。 （联系我们开通授权或提高限制） |
| 10018  | 用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注 |
| 10019  | 该错误码表示返回结果疑似敏感，建议拒绝用户继续交互           |
| 10110  | 服务忙，请稍后再试。                                         |
| 10163  | 请求引擎的参数异常 引擎的schema 检查不通过                   |
| 10222  | 引擎网络异常                                                 |
| 10223  | LB找不到引擎节点                                             |
| 10907  | token数量超过上限。对话历史+问题的字数太多，需要精简输入。   |
| 11200  | 授权错误：该appId没有相关功能的授权 或者 业务量超过限制（联系我们开通授权或提高限制） |
| 11201  | 授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制） |
| 11202  | 授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制） |
| 11203  | 授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制） |