> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 将 LoRA 适配器合并到基座模型

> 将 LoRA 或适配器检查点合并到其基座模型权重中。在导出为 GGUF、MLX、MNN 或 QNN 等格式之前需要进行合并。

使用此接口将训练好的 LoRA 适配器合并回基座模型权重。合并会在 `merged` 产物路径下生成全量权重模型，这是在导出为 GGUF、MLX、MNN 或 QNN 等部署格式之前所必需的。

## 方法与路径

```http theme={null}
POST /v1/models/:id/merge
```

## 认证

在 `Authorization` 头中以 Bearer 令牌的形式携带你的 PIN API 令牌或 JWT。

```http theme={null}
Authorization: Bearer <token>
```

## 路径参数

<ParamField path="id" type="string" required>
  模型标识符（例如 `md_abc123def456`）。
</ParamField>

## 请求体

无需请求体。

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/models/md_abc123def456/merge" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```
</CodeGroup>

## 响应

返回标准的 PIN 成功信封，包含合并状态。

<ResponseField name="code" type="integer" required>
  成功为 `0`，出错为非零值。
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="属性">
    <ResponseField name="model_id" type="string">
      模型标识符。
    </ResponseField>

    <ResponseField name="status" type="string">
      合并成功完成时返回 `ready`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  可读消息（成功时为空）。
</ResponseField>

### 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "model_id": "md_abc123def456",
    "status": "ready"
  },
  "message": ""
}
```

## 合并流程

1. 系统校验模型存在且当前未在合并中。
2. 它使用 PEFT 的 `merge_and_unload` 生成临时 Python 脚本，将适配器融合进基座权重。
3. 合并后的权重保存到模型的 `merged` 产物目录。
4. 成功后，模型状态恢复为 `ready`，并更新 `artifact_paths.merged`。

## 错误

| Code | HTTP | 含义                |
| ---- | ---- | ----------------- |
| 401  | 401  | 缺失或无效的 Bearer 令牌。 |
| 404  | 404  | 模型不存在或不属于你。       |
| 409  | 409  | 该模型已在合并中。         |
| 500  | 500  | 合并脚本执行失败。         |

## 说明

* 若在合并前调用 `POST /v1/models/:id/export`，导出服务会先自动触发合并。
* 对于以全参数方法训练的模型（`pretrain`、`qat`、`distill` 且 `mode=full`），无需合并，因为其输出已是全量权重。