精调服务_HTTP协议

# 精调服务_HTTP协议

## 1. 接口说明

协议 ：HTTP
请求方法：POST
默认请求地址如下：

```http
http://maas-api.cn-huabei-1.xf-yun.com/v1
```

部分模型因为部署原因可能略有差异，具体可参考**服务管控** > **模型服务列表**右侧调用信息。

## 2. 接口请求

### 2.1 请求示例

下面是一个 HTTP 请求的 Python Demo 示例：

```python
from openai import OpenAI

api_key = "<从服务管控页面获取 对应服务的APIKey>"  # 请替换为您的 API Key  
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"

client = OpenAI(api_key=api_key,base_url=api_base)

try:
    response = client.chat.completions.create(
        model="<从服务管控获取要访问服务的modelID>",
        messages=[{"role": "user", "content": "你好"}],
        stream=False,
        temperature=0.7,
        max_tokens=4096,
        extra_headers={"lora_id": "0"},  
        stream_options={"include_usage": True},
        extra_body={"search_mod": "force", "show_ref_label": True} 
    )
    # 只对支持深度思考的模型才有此字段
    print(response.choices[0].message.reasoning_content)
    # 只对支持联网检索的模型，开启检索返回信源列表时才有此字段
    print(response.choices[0].message.plugins_content)
    print(response.choices[0].message.content)
    
except Exception as e:
    print(f"Error: {e}")
```

**注意**：在使用demo之前，请务必替换 `api_key` 为您的API Key。

如果想使用 HTTP 请求的 流式输出，请参考如下实例：

```python
from openai import OpenAI

api_key = "<从服务管控页面获取 对应服务的APIKey>"  # 请替换为您的 API Key  
api_base = "http://maas-api.cn-huabei-1.xf-yun.com/v1"

client = OpenAI(api_key=api_key,base_url=api_base)

try:
    response = client.chat.completions.create(
        model="<从服务管控获取要访问服务的modelID>",
        messages=[{"role": "user", "content": "你好"}],
        stream=True,
        temperature=0.7,
        max_tokens=4096,
        extra_headers={"lora_id": "0"},  
        stream_options={"include_usage": True},
        extra_body={"search_disable": False, "show_ref_label": True} 
    )

full_response = ""
    for chunk in response:
        # 只对支持深度思考的模型才有此字段
        if hasattr(chunk.choices[0].delta, 'reasoning_content') and chunk.choices[0].delta.reasoning_content is not None:
            reasoning_content = chunk.choices[0].delta.reasoning_content
            print(reasoning_content, end="", flush=True)  # 实时打印思考模型输出的思考过程每个片段

# 只对支持联网检索的模型，开启检索返回信源列表时才有此字段
        if hasattr(chunk.choices[0].delta, 'plugins_content') and chunk.choices[
            0].delta.plugins_content is not None:
            plugins_content = chunk.choices[0].delta.plugins_content
            print(plugins_content, end="", flush=True)  # 实时打印联网检索信源结果的每个片段
        
        if hasattr(chunk.choices[0].delta, 'content') and chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)  # 实时打印每个片段
            full_response += content
    
    print("\n\n ------完整响应：", full_response)    
except Exception as e:
    print(f"Error: {e}")
```

**注意**：在使用demo之前，请务必替换 `api_key` 为您的API Key。

下面是一个基于 HTTP 协议的 CURL 请求模板：
```bash
curl -X POST \
     -H "Authorization: Bearer <API_KEY>" \
     -H "Content-Type: application/json" \
     -H "lora_id: 0" \
     -d '{
           "model": "<MODEL_ID>",
           "messages": [{"role": "user", "content": "你好"}],
           "temperature": 0.7,
           "max_tokens": 4096,
           "search_disable": false,
           "show_ref_label": true
         }' \
     "http://maas-api.cn-huabei-1.xf-yun.com/v1/chat/completions"
```
**注意**：请务必替换 `api_key` 为您的API Key。

###  2.2 请求参数

#### 2.2.1 Header 参数

| 参数    | 类型   | 是否必填 | 要求       | 说明                                  |
| ------- | ------ | -------- | ---------- | ------------------------------------- |
| lora_id | string | 否       | 默认值为 0 | 通过传递 `lora_id` 加载特定的LoRA模型 |

#### 2.2.2 Body 参数

| 参数           | 类型    | 是否必填 | 要求                                           | 说明                                                         |
| -------------- | ------- | -------- | ---------------------------------------------- | ------------------------------------------------------------ |
| model          | string  | 是       |                                                | 指定要调用的对话生成模型ID                                   |
| messages       | array   | 是       | `[{"role": "user", "content":"用户输入内容"}]` | 表示对话上下文的消息列表，支持多轮对话交互。其中，`role` 用于标识消息发送方（例如 `user` 表示用户、`assistant` 表示模型回复），`content` 则为实际文本内容。 |
| messages.role | string | 是 |  | 角色，user表示用户，assistant表示大模型，system表示命令 |
| messages.content | string | 是 |  | 角色对应的文本内容 |
| stream         | boolean | 否       | 取值为 `true` 或 `false`，默认值为 `false`     | 指定是否采用流式响应模式。若设置为 `true`，系统将逐步返回生成的回复内容；否则，将一次性返回完整响应 |
| temperature    | float   | 否       | 取值为`[0,1]`,默认值为`0.7`                    | 核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高 |
| max_tokens     | int     | 否       | 取值为`[1,8192]`，默认值为`2048`               | 限制生成回复的最大 token 数量，DeepSeek-R1和DeepSeek-V3 最大可支持到 32768 |
| search_disable | boolean | 否 | 取值为 `true` 或 `false`，默认值为 `true` | 控制联网检索相关功能，**仅DeepSeek-R1和DeepSeek-V3支持该功能**。`search_disable`关闭联网检索功能，取值：[true,false]；默认值：true，输出内容是否结合联网检索结果会根据输入文本自动判断。 |
| show_ref_label | boolean | 否 | 取值为 `true` 或 `false`，默认值为 `false` | 展示检索信源信息，取值：[true,false]；默认值：false，开启联网检索功能后当该参数设置为true且触发了联网检索功能时，会在响应数据中新增返回检索信源列表；否则仅返回大模型回复结果 |
| enable_thinking | boolean | 否 | 取值为 `true` 或 `false`，默认值为 `false` | `enable_thinking`切换思考模式，该参数**仅Qwen3 MOE系列模型支持**。取值：[true,false]；默认值：true，支持在单一模型内无缝切换思考模式（用于复杂的逻辑推理、数学和编程）和非思考模式（用于高效、通用的对话） |
| stream_options | object  | 否       | 默认值为`{"include_usage": True}`              | 针对流式响应模式的扩展配置，如控制是否在响应中包含API调用统计信息等附加数据。 |

## 3. 接口响应

### 3.1 响应示例

#### 3.1.1 成功响应示例
关闭联网检索或不返回检索信源时，返回结构如下：

```python
Response: ChatCompletion(
    id='cht000b920a@dx194e0205ccbb8f3700',
    choices=[
        Choice(
            finish_reason='stop',
            index=0,
            logprobs=None,
            message=ChatCompletionMessage(
                content='大模型回复',
                refusal=None,
                role='assistant',
                audio=None,
                function_call=None,
                tool_calls=None
            )
        )
    ],
    created=1738927005,
    model=None,
    object='chat.completion',
    service_tier=None,
    system_fingerprint=None,
    usage=CompletionUsage(
        completion_tokens=42,
        prompt_tokens=44,
        total_tokens=86,
        completion_tokens_details=None,
        prompt_tokens_details=None
    )

```
开启联网检索且返回检索信源是，返回结构如下：
```python
ChatCompletion(
    id='cht000b8e42@dx19590107ba3b8f2700', 
    choices=[
        Choice(
            finish_reason='stop', 
            index=0, 
            logprobs=None, 
            message=ChatCompletionMessage(
                content='大模型回复', 
                refusal=None, 
                role='assistant', 
                audio=None, 
                function_call=None, 
                tool_calls=None, 
                reasoning_content='', 
                plugins_content=[
                    {
                        'name': 'ifly_search', 
                        'content': '[{"index":1,"url":"https://xxx.com/xxx/doc.html","title":"信源标题"}]'
                    }
                ]
            )
        )
    ], 
    created=1741878776, 
    model='xdeepseekv3', 
    object='chat.completion', 
    service_tier=None, 
    system_fingerprint=None, 
    usage=CompletionUsage(
        completion_tokens=346, 
        prompt_tokens=1124, 
        total_tokens=1470, 
        completion_tokens_details=None, 
        prompt_tokens_details=None
    )
)
```

#### 3.1.2 异常结果示例

```json
Error: Error code: 403 - {'error': {'message': '该令牌无权使用模型：xqwen257bxxx (request id: 2025020809381060443349905703260)', 'type': 'one_api_error'}}
```

### 3.2 响应数据参数

字段说明如下：

| 字段名                                     | 类型   | 字段说明                                             |
| ------------------------------------------ | ------ | ---------------------------------------------------- |
| id                                         | string | 唯一标识符，标识本次对话调用的唯一ID，用于跟踪和调试 |
| choices                                    | array  | 包含模型生成回复候选项的数组                         |
| &nbsp;&nbsp;•finish_reason                 | string | 指示回复生成结束的原因，如`"stop"`                   |
| &nbsp;&nbsp;•index                         | int    | 回复候选项在数组中的索引位置，从0开始                |
| &nbsp;&nbsp;•logprobs                      | object | 如启用token概率日志，则返回具体信息                  |
| &nbsp;&nbsp;•message                       | object | 描述回复消息内容的对象，其内部字段如下               |
| &nbsp;&nbsp;&nbsp;&nbsp;◦content           | string | 模型生成的回复文本内容                               |
| &nbsp;&nbsp;&nbsp;&nbsp;◦reasoning_content | string | 模型生成的思考文本内容(支持深度思考的模型才有此字段) |
| &nbsp;&nbsp;&nbsp;&nbsp;◦plugins_content | array | 联网检索的信源结果列表(支持联网检索的模型才有此字段) |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;◦name | string | 联网检索插件名称ifly_search等 |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;◦name | string | 联网检索插件结果，此为信源结果列表，`index`序号，`url`信源地址，`title`信源标题|
| &nbsp;&nbsp;&nbsp;&nbsp;◦refusal           | object | 模型拒绝回答时返回拒绝信息                           |
| &nbsp;&nbsp;&nbsp;&nbsp;◦role              | string | 消息发送方，通常为`"assistant"`                      |
| &nbsp;&nbsp;&nbsp;&nbsp;◦audio             | object | 如支持语音回复则返回音频数据                         |
| &nbsp;&nbsp;&nbsp;&nbsp;◦function_call     | objec  | 模型调用外部函数时返回调用信息                       |
| &nbsp;&nbsp;&nbsp;&nbsp;◦tool_calls        | object | 模型调用工具时返回调用详情，                         |
| created                                    | int    | 响应生成时间的Unix时间戳（秒级）                     |
| model                                      | string | 实际调用的模型名称                                   |
| object                                     | string | 表示响应对象类型                                     |
| service_tier                               | string | 表示调用所属的服务层级                               |
| system_fingerprint                         | string | 系统指纹或配置标识                                   |
| usage                                      | object | 包含token使用统计信息，其内部字段如下：              |
| &nbsp;&nbsp;•completion_tokens             | int    | 回复文本消耗的token数量                              |
| &nbsp;&nbsp;•prompt_tokens                 | int    | 输入prompt消耗的token数量                            |
| &nbsp;&nbsp;•total_tokens                  | int    | prompt与回复消耗token数量的总和                      |
| &nbsp;&nbsp;•completion_tokens_details     | object | 回复生成过程中token的详细统计信息，若无则为`null`    |
| &nbsp;&nbsp;•prompt_tokens_details         | object | prompt部分token的详细统计信息                        |
|

##  4 . 错误码列表

| 错误码                                 | 原因                                      | 解决方案                                                |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------- |
| 401-无效的身份验证                     | 身份验证无效。                            | 确保使用正确的API密钥及请求组织。                       |
| 401-提供的API密钥不正确                | 请求的API密钥不正确。                     | 检查所用API密钥是否正确，清除浏览器缓存或生成新的密钥。 |
| 403-不支持的国家、地区或领土           | 您正在从不支持的国家、地区或领土访问API。 | 请参考相关页面获取更多信息。                            |
| 429-请求速率限制已达上限               | 您发送请求过快。                          | 控制请求频率，阅读速率限制指南。                        |
| 429-超出当前配额，请检查计划和计费详情 | 您的额度已用尽或已达到每月最高消费限制。  | 购买更多额度或了解如何提高使用限制。                    |
| 500-服务器处理请求时发生错误           | 服务器内部出现问题。                      | 稍后重试请求；若问题持续，请联系我们查看状态页面。      |
| 503-引擎当前过载，请稍后重试           | 服务器流量过大。                          | 稍候重试您的请求。                                      
|