# 插件 (/docs/cloud/services/model/guides/plugins)



插件在模型调用前后处理请求或响应，让模型可以使用经过转换的输入。它们不会改变模型本身的原生能力。`file-parser` 是第一个插件：在需要时，把文档或图片转换为文字，再交给你选择的模型。

同一套 `plugins` 参数适用于 `/model/v1/chat/completions`、`/model/v1/messages` 和 `/model/v1/responses` 的创建请求，支持流式和非流式。参数由平台消费，不会作为模型参数传给上游。

## 配置与默认行为 [#配置与默认行为]

在请求体中加入 `plugins` 数组，每个配置用 `id` 指定插件：

```json
{
  "plugins": [
    { "id": "file-parser", "enabled": true }
  ]
}
```

未传 `plugins` 或传 `plugins: []` 都表示沿用默认配置，**不表示关闭**。当前文件解析默认开启；模型能原生处理的 PDF 和图片，在符合模型限制时直接传递。否则，文字 PDF 和 Office 文档在本地提取文字，扫描页使用 OCR，图片使用 OCR 和视觉描述。提取出的文字占用主模型的上下文窗口。

关闭转换使用：

```json
{
  "plugins": [
    { "id": "file-parser", "enabled": false }
  ]
}
```

关闭后，原生支持的输入仍可使用；模型不支持的输入会被拒绝。配置会检查插件 ID、字段和取值，未知配置不会被静默忽略。

### PDF 处理方式 [#pdf-处理方式]

| `pdf.engine` | 行为                                               |
| ------------ | ------------------------------------------------ |
| `auto`（默认模式） | 优先原生处理；需要转换时提取文字，并对扫描页或文字不足的页使用 OCR。             |
| `native`     | 只允许原生 PDF 输入。模型不支持或超过原生限制时拒绝，不自动转为文字。            |
| `ocr`        | 强制走文字转换，即使模型支持原生 PDF；有可用文字的页仍本地提取，需要识别的页才调用 OCR。 |

请求中**省略 `pdf.engine` 会继承默认配置**；没有租户或平台覆盖时即为自动模式。当前请求参数只接受显式的 `native` 或 `ocr`，不能用字符串 `"auto"` 覆盖已有默认。可在控制台将租户 PDF 默认方式设为自动。

```json
{
  "plugins": [
    { "id": "file-parser", "pdf": { "engine": "ocr" } }
  ]
}
```

`pdf.engine` 只影响 PDF。可用 `"image": { "describe": false }` 关闭非原生图片转换；它不关闭原生视觉输入，也不影响文档。

### 配置优先级 [#配置优先级]

从高到低：**平台策略 > 租户锁定 > 本次请求 > 租户默认 > 插件默认**。

平台策略决定的值不可被覆盖。租户锁定后，请求尝试改变锁定值会返回 `PLUGIN_SETTING_LOCKED`。没有锁定的字段可以在本次请求中覆盖，且不会修改租户默认配置。文件大小、页数等平台限制不可通过请求调整。

## 费用 [#费用]

* 本地文字提取不产生额外模型用量；转换后的文字仍按主模型输入计费。
* OCR 按实际处理页数计量，图片描述按描述模型的输入、缓存输入和输出用量计量；单价以所用模型的价格为准。
* OCR、图片描述和主模型是各自的用量记录。主模型失败不会抹掉已经发生的转换用量。
* 命中解析缓存不发起新的转换子调用，因此不新增这部分用量；下一轮主模型仍按实际输入和输出计费。

## 解析注明与下一轮带回 [#解析注明与下一轮带回]

转换成功的响应会携带文件注明（annotations）。保留完整对象，不要修改哈希或解析内容：

```json
{
  "type": "file",
  "file": {
    "hash": "<原样保留服务返回的哈希>",
    "name": "notes.pdf",
    "content": [{ "type": "text", "text": "解析出的文字" }]
  }
}
```

| 入口                 | 非流式位置                                                          | 流式位置                                                                   |
| ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Chat Completions   | `choices[].message.annotations`                                | `choices[].delta.annotations`，每个 choice 返回一次                           |
| Anthropic Messages | 响应消息顶层 `annotations`                                           | `message_start.message.annotations`                                    |
| Responses          | `output[]` 中 message 的 `content[]` 内 `output_text.annotations` | `response.content_part.done`、`response.output_item.done` 和响应终态中的对应文字快照 |

已有的引用注明及其下标会保留；Responses 的未完成快照不插入文件注明，完成快照才附加。Messages 的顶层字段和 Responses 中的 `type: "file"` 是平台扩展；不要把文件注明变成 Anthropic content block。只有实际转换才产生这些注明，原生直传不产生。Responses 若只返回工具调用、拒绝块或空输出，不会为携带注明而合成文字消息。

下一轮保留原始用户输入和上一轮 assistant 内容，把注明一同带回：

```js
// Chat Completions
messages.push(response.choices[0].message);

// Anthropic Messages：保留顶层扩展字段
messages.push({
  role: "assistant",
  content: response.content,
  annotations: response.annotations,
});

// Responses：保留 output_text 的 annotations
input.push(...response.output);
```

然后追加新的用户问题。流式客户端同样保留聚合结果中的注明；若自行组装消息，需从上述事件位置收集它们。SDK 类型未声明扩展字段时，使用其额外字段机制或读取原始 JSON。

带回内容与服务端解析结果、原文件、配置及模型能力匹配时，会跳过重新解析。修改内容、切换配置或缓存不可用时，不保证复用；客户端注明不能自行证明“已解析”。即使不再携带原文件，注明中的文字也会作为普通对话上下文送给模型。单独传 `previous_response_id` 不等于显式带回文件注明。

## 查看模型支持方式 [#查看模型支持方式]

`GET /model/v1/models` 的 `architecture.input_modalities` 使用 OpenRouter 形状，只列原生模态。原生 PDF 能力表示为 `file`，不会因启用插件而加入这一数组。

扩展字段 `x_praxis.input_modalities` 按输入类型标注 `native`、`converted` 或 `unsupported`：

```json
{
  "architecture": { "input_modalities": ["text"] },
  "x_praxis": {
    "input_modalities": {
      "text": "native",
      "image": "converted",
      "pdf": "converted",
      "docx": "converted",
      "pptx": "converted",
      "xlsx": "converted",
      "audio": "unsupported",
      "video": "unsupported"
    }
  }
}
```

这是一个仅支持原生文字的对话模型的示例。标注由模型能力和已注册插件推导；`converted` 表示存在转换路径，实际请求还受租户设置、请求配置和限额约束。嵌入、OCR 等非对话调用不因此获得对话插件。音频、视频目前没有转换插件，只有模型原生支持时才可输入。

## 限制 [#限制]

* 需要转换的文件必须提供内联内容，或使用当前入口支持的已授权文件引用；插件不下载任意外部 URL。
* 当前支持 PDF、DOCX、PPTX、XLSX 和图片转换。Office 提取正文、幻灯片文字及单元格值，不解析嵌入对象或其中的图片。
* 单文件最多 10 MiB，每请求累计最多 20 MiB；PDF 解析最多 100 页，付费 OCR 最多 20 页，每批最多 10 页；每请求最多 4 个付费子调用、同时最多 2 个。
* 转换总时限为 90 秒；OCR 子调用最多 45 秒，图片描述最多 30 秒。流式转换期间可能先收到 `: PRAXIS PROCESSING` 保活注释，它不是模型输出。
* 提取文字最多 1,000,000 字符，表格每 sheet 最多 1,000 行。模型自身的上下文和输入限制仍然适用。
* Responses 仅在创建时转换新提交的输入；retrieve、cancel 等操作不重新转换。需要转换的 `background: true` 请求返回 `PLUGIN_BACKGROUND_UNSUPPORTED`。
* 并发请求同时未命中缓存时，可能各自发起付费转换。主模型失败时，当前接口不保证返回已解析的文件注明。