# Parser管理对象与调用规则

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

<span id="prepare"></span>

## 调用前准备

BASE_URL、MOI_KEY与WORKSPACE_ID来自同一环境。BACKEND_ID/ENDPOINT_ID由同环境Parser读取或创建取得。示例地址和key-example-*都是占位值，生产支持及真实服务需另行确认。

/parser管理入口使用普通产品身份，按X-Workspace-ID选租户。后端kind为parser，规范ID为正十进制；不能把LLM或Embedding的同值整数当作同一对象。集合/详情/端点读取要求model_backend.read，创建要求工作区model_backend.create，更新/端点写入要求对象update，删除要求delete；Router分别要求工作区model_router.read/update。

原始文件解析与转换不在这十个产品管理动作中，见[相关接口](index.md)。普通PAT、系统密钥与已验证Worker执行身份不能相互替代。

<span id="responses"></span>

## HTTP与客户端返回

| 动作 | HTTP data | SDK/CLI适配 |
| --- | --- | --- |
| 后端列表 | 数组，空可null | backends集合。 |
| 端点列表 | 数组，空可null | endpoints集合。 |
| 创建/详情/更新 | 后端对象 | ProviderBackend；不是模型配置对象。 |
| 创建端点 | 端点对象 | ProviderEndpoint。 |
| 删除/设置端点状态 | null | 客户端可合成success:true，非服务端额外字段。 |
| Router读取/写入 | 配置对象 | ProviderRouterConfig。 |

十动作均HTTP200、code="OK"、msg="OK"；没有LLM工作区式201/204，也没有total/对外分页。

| 后端字段 | 类型 | 说明 |
| --- | --- | --- |
| id | integer | Parser后端ID。 |
| name | string | 名称。 |
| type | string | PARSER_*协议类型。 |
| timeout_seconds | integer | 超时秒数；创建默认3600，配置上限86400。 |
| supported_mime_types | array（字符串数组）或null | MIME声明，空为catch-all；不测试实际解析能力。 |
| endpoints | array（对象数组） | 非空读取可带在线端点，空时省略；普通创建/更新不补端点。 |
| created_at | integer | Unix秒。 |
| updated_at | integer | Unix秒。 |

返回对象没有api_key、api_keys_encrypted或models。便捷SDK复用ProviderBackend，出现这些属性的默认空值不代表HTTP返回了字段。

Parser类型包括PARSER_MINERU、PARSER_UNOSERVER、PARSER_OPENXML、PARSER_PADDLEOCR、PARSER_DEV、PARSER_WPS_CONVERTER、PARSER_LIBREOFFICE、PARSER_MOI_AUDIO_SERVICE。创建的非Parser值回退MINERU，不能据保存成功证明适配器/部署支持。普通解析选择器排除WPS_CONVERTER/LIBREOFFICE，两者属于转换路径；DEV也不作为生产能力承诺。

| 端点字段 | 类型 | 说明 |
| --- | --- | --- |
| id | integer | 端点ID；离线前保留。 |
| backend_id | integer | 所属Parser后端。 |
| address | string | 接入地址。 |
| status | string | ONLINE/OFFLINE。设置输入先trim+大写，非法按ONLINE。 |
| created_at | integer | Unix秒。 |
| updated_at | integer | Unix秒。 |

Parser集合JOIN、后端详情和端点读取均过滤离线。DAO内部按ID批量读取，不表示公开支持cursor/page。状态保存不测健康；无独立端点删除动作，离线不等于删除。

## 密钥池与更新

创建/更新的api_keys_encrypted是有序池；每项必须去空白后非空，规范化时trim但不自行去重。非空池优先于同请求api_key，保存的单密钥镜像池首项。名称和单密钥的空值、超时非正值均不表达清除；MIME只有非空数组更新，[]保留旧声明。

更新池省略/null保留，非空数组完整替换；[]退回单密钥模式。未同时提供非空api_key时保留原单密钥/首项，不是清除全部凭据。DAO会把单密钥规范化成一项池，不能用JSON数组必须为空判断模式转换。已有池多于一项而只传api_key会返回400/ErrParamInvalid；完整替换应保留调用者自己的全部池配置，响应不回传池。

## Router与运行效果

| 字段 | 类型 | 写入默认 |
| --- | --- | --- |
| strategy | string | 非法或省略按ROUND_ROBIN；接受LEAST_CONNECTIONS/MODEL_BASED。 |
| health_check_interval | integer | 非正/省略按30秒。 |
| max_retries | integer | 非正/省略按0。 |
| session_affinity | boolean | 省略/null按false。 |

GET缺配置时owner临时默认为ROUND_ROBIN/30/2/false，不能据此证明已持久化。PUT按请求加默认值完整写入，DAO更新已有行；

所选Parser选择器按精确MIME、catch-all、租户/系统候选和在线端点轮换，未读取strategy字段。声明MIME可含精确类型或*/*，空声明为catch-all；系统显式MIME可在特定租户catch-all场景优先。

<span id="errors"></span>

## 错误与结果确认

错误使用string code/msg。输入、超时上限、错误类型/ID及单密钥覆盖多池可为400/ErrParamInvalid，对象缺失可为404，当前角色拒绝403，依赖故障503，其余按各入口映射。绑定未启用统一严格拒绝未知键；额外字段不能据成功当作已写入。

配置、路由解析、文件执行和实际结果分别确认；
