mirror of
https://github.com/opendatalab/MinerU.git
synced 2026-10-25 17:42:08 +08:00
myhloli
7f250e2331
Converge the SDK, Gradio, remote CLI, Doclib and Router on Tasks with hash-based uploads, per-file result URLs, task listing and optional model output. Preserve Files and the synchronous file_parse wrapper while removing standalone Uploads/Jobs and local-path HTTP inputs. Migrate contract, lifecycle, transport and real-document regression coverage; update documentation and HTTP examples. Validation: 1452 passed, 3 conditional skips, plus targeted final PDF checks. BREAKING CHANGE: clients and workers must use Tasks; standalone Uploads/Jobs endpoints and local-source/inline HTTP options have been removed.
332 lines
11 KiB
Markdown
332 lines
11 KiB
Markdown
# Chat 与 Responses
|
||
|
||
状态: Draft
|
||
读者: API 使用者、SDK 开发者、服务端开发者
|
||
范围: OpenAI-compatible 文档对话接口
|
||
来源: 由根目录旧 Unified API 底稿迁移整理而来
|
||
|
||
## 定位
|
||
|
||
Chat Completions 和 Responses 面向细粒度文档理解场景，例如单张图片 OCR、单个表格提取或一段文本识别。完整 PDF、DOCX、PPTX 等多页文档解析应使用 [Tasks](tasks.md)。
|
||
|
||
两套接口都只支持单轮请求，不维护服务端会话历史。
|
||
|
||
## POST `/v1/chat/completions`
|
||
|
||
创建 Chat Completion。请求形态兼容 OpenAI Chat Completions 的核心字段。
|
||
|
||
```json
|
||
{
|
||
"model": "mineru-4.0.11",
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": [
|
||
{
|
||
"type": "image_url",
|
||
"image_url": {
|
||
"url": "data:image/png;base64,iVBORw0KGgo..."
|
||
}
|
||
},
|
||
{
|
||
"type": "text",
|
||
"text": "Text Recognition:"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"stream": false,
|
||
"temperature": 0.7,
|
||
"top_p": 1.0,
|
||
"max_completion_tokens": 4096,
|
||
"n": 1
|
||
}
|
||
```
|
||
|
||
请求字段:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `messages` | array | 是 | 消息列表。 |
|
||
| `model` | string | 是 | 虚拟模型 ID（`mineru-<服务版本>`），来自 `GET /v1/models`，精确匹配当前部署广告值；不用于选择引擎。 |
|
||
| `tier` | string | 否 | MinerU 扩展字段：解析质量档（`flash`/`basic`/`standard`/`advanced`），内部复用 Tasks 的 tier 路由与默认选择策略。OpenAI SDK 通过 `extra_body` 传入。 |
|
||
| `stream` | bool | 否 | 是否流式输出，默认 `false`。 |
|
||
| `stream_options.include_usage` | bool | 否 | `stream=true` 时，最终 chunk 是否包含 usage。 |
|
||
| `temperature` | number | 否 | 采样温度，范围 `[0, 2]`。 |
|
||
| `top_p` | number | 否 | 核采样，范围 `[0, 1]`。 |
|
||
| `max_tokens` | integer | 否 | 兼容字段，建议使用 `max_completion_tokens`。 |
|
||
| `max_completion_tokens` | integer | 否 | 最大输出 token 数。 |
|
||
| `stop` | string 或 array | 否 | 最多 4 个停止序列。 |
|
||
| `seed` | integer | 否 | 尽量确定性采样。 |
|
||
| `frequency_penalty` | number | 否 | 兼容 OpenAI 字段。 |
|
||
| `presence_penalty` | number | 否 | 兼容 OpenAI 字段。 |
|
||
| `reasoning_effort` | string | 否 | 接受但可忽略，保留给未来模型。 |
|
||
| `n` | integer | 否 | 当前仅允许 `1`。 |
|
||
|
||
### Message
|
||
|
||
支持 role:
|
||
|
||
| role | content |
|
||
|------|---------|
|
||
| `system` | string 或 text part 数组。 |
|
||
| `developer` | string 或 text part 数组，与 `system` 等价处理。 |
|
||
| `user` | string 或多模态 part 数组。 |
|
||
|
||
不支持 `assistant`、`tool`、`function` role。
|
||
|
||
`user` content part:
|
||
|
||
| part | 结构 | 说明 |
|
||
|------|------|------|
|
||
| `text` | `{"type":"text","text":"..."}` | 文本指令。 |
|
||
| `image_url` | `{"type":"image_url","image_url":{"url":"..."}}` | 图片 URL 或 base64 data URI。`detail` 可传但忽略。 |
|
||
|
||
输入限制:
|
||
|
||
| 限制项 | 值 |
|
||
|--------|----|
|
||
| 图片或 file 数量 | 每条消息最多 1 个，二选一。 |
|
||
| 图片文件大小 | 小于 10 MiB。 |
|
||
| 图片分辨率 | 小于 3500 x 3500。 |
|
||
|
||
### 非流式响应
|
||
|
||
```json
|
||
{
|
||
"id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
|
||
"object": "chat.completion",
|
||
"created": 1741569952,
|
||
"model": "mineru-4.0.11",
|
||
"system_fingerprint": "fp_44709d6fcb",
|
||
"choices": [
|
||
{
|
||
"index": 0,
|
||
"message": {
|
||
"role": "assistant",
|
||
"content": "# 文本识别结果\n\n这是从图片中识别出的文字内容..."
|
||
},
|
||
"finish_reason": "stop"
|
||
}
|
||
],
|
||
"usage": {
|
||
"prompt_tokens": 120,
|
||
"completion_tokens": 86,
|
||
"total_tokens": 206
|
||
}
|
||
}
|
||
```
|
||
|
||
响应字段:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | string | Completion ID。 |
|
||
| `object` | string | 固定为 `"chat.completion"`。 |
|
||
| `created` | integer | Unix 秒级时间戳。 |
|
||
| `model` | string | 实际使用的模型。 |
|
||
| `system_fingerprint` | string | 后端配置指纹。 |
|
||
| `choices[].index` | integer | 候选索引。 |
|
||
| `choices[].message.role` | string | 固定为 `"assistant"`。 |
|
||
| `choices[].message.content` | string 或 null | 输出文本。 |
|
||
| `choices[].finish_reason` | string | `stop`、`length` 或 `content_filter`。 |
|
||
| `usage` | object | token 用量。 |
|
||
|
||
### 流式响应
|
||
|
||
`stream=true` 时返回 SSE，每行 `data:` 后是一个 `chat.completion.chunk` JSON 对象，最后以 `data: [DONE]` 结束。
|
||
|
||
```text
|
||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"mineru-4.0.11","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
|
||
|
||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"mineru-4.0.11","choices":[{"index":0,"delta":{"content":"# 文本"},"finish_reason":null}]}
|
||
|
||
data: [DONE]
|
||
```
|
||
|
||
如果 `stream_options.include_usage=true`，最终 JSON chunk 可以包含 `usage`，且 `choices` 为空数组。
|
||
|
||
### 不支持的 Chat 参数
|
||
|
||
以下参数不支持。实现可以返回 `400 unsupported_parameter`，也可以在明确兼容策略下忽略，但 SDK 不应依赖它们生效:
|
||
|
||
- `tools`、`tool_choice`、`function_call`、`functions`、`parallel_tool_calls`
|
||
- `audio`、`modalities`
|
||
- `web_search_options`
|
||
- `prediction`
|
||
- `response_format`
|
||
- `logprobs`、`top_logprobs`
|
||
- `logit_bias`
|
||
- `service_tier`
|
||
- `store`、`metadata`
|
||
- `safety_identifier`、`prompt_cache_key`、`prompt_cache_retention`、`user`、`verbosity`
|
||
|
||
Chat 错误:
|
||
|
||
| HTTP | code | 场景 |
|
||
|------|------|------|
|
||
| 400 | `invalid_request` | 消息结构非法、role 不支持、缺少模型等。 |
|
||
| 400 | `unsupported_parameter` | 传入当前不支持的参数。 |
|
||
| 404 | `model_not_found` | 模型不存在。 |
|
||
| 413 | `content_too_large` | 图片或输入超过限制。 |
|
||
| 429 | `rate_limit_exceeded` | 触发 chat 类限流。 |
|
||
| 503 | `service_unavailable` | 模型服务不可用。 |
|
||
|
||
## POST `/v1/responses`
|
||
|
||
创建 Response。该接口与 Chat Completions 功能重叠，但输入输出采用 typed item list。
|
||
|
||
```json
|
||
{
|
||
"model": "mineru-4.0.11",
|
||
"input": [
|
||
{
|
||
"role": "user",
|
||
"content": [
|
||
{ "type": "input_image", "image_url": "https://example.com/page.png" },
|
||
{ "type": "input_text", "text": "Text Recognition:" }
|
||
]
|
||
}
|
||
],
|
||
"stream": false,
|
||
"temperature": 0.7,
|
||
"top_p": 1.0,
|
||
"max_output_tokens": 4096,
|
||
"store": false
|
||
}
|
||
```
|
||
|
||
请求字段:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:--:|------|
|
||
| `input` | string 或 array | 是 | 字符串或 EasyInputMessage 数组。 |
|
||
| `instructions` | string | 否 | 系统指令，等价于 Chat 的 system message。 |
|
||
| `model` | string | 是 | 模型 ID。 |
|
||
| `stream` | bool | 否 | 是否流式输出。 |
|
||
| `temperature` | number | 否 | 采样温度。 |
|
||
| `top_p` | number | 否 | 核采样。 |
|
||
| `max_output_tokens` | integer | 否 | 最大输出 token 数。 |
|
||
| `reasoning.effort` | string | 否 | 接受但可忽略。 |
|
||
| `reasoning.summary` | string | 否 | 接受但可忽略。 |
|
||
| `store` | bool | 否 | 当前仅允许 `false`。 |
|
||
|
||
EasyInputMessage:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `role` | string | `system`、`developer` 或 `user`。 |
|
||
| `content` | string 或 array | 文本或多模态 part。 |
|
||
|
||
Content part:
|
||
|
||
| part | 结构 | 说明 |
|
||
|------|------|------|
|
||
| `input_text` | `{"type":"input_text","text":"..."}` | 文本。 |
|
||
| `input_image` | `{"type":"input_image","image_url":"..."}` | 图片 URL 或 data URI。 |
|
||
|
||
不支持 assistant role、tool/function item、reasoning item、conversation 状态 item。
|
||
|
||
### 非流式响应
|
||
|
||
```json
|
||
{
|
||
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
|
||
"object": "response",
|
||
"created_at": 1741476542,
|
||
"status": "completed",
|
||
"model": "mineru-4.0.11",
|
||
"output": [
|
||
{
|
||
"type": "message",
|
||
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
||
"status": "completed",
|
||
"role": "assistant",
|
||
"content": [
|
||
{
|
||
"type": "output_text",
|
||
"text": "该文档主要介绍了...",
|
||
"annotations": []
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"usage": {
|
||
"input_tokens": 36,
|
||
"output_tokens": 87,
|
||
"total_tokens": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
响应字段:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | string | Response ID。 |
|
||
| `object` | string | 固定为 `"response"`。 |
|
||
| `created_at` | integer | Unix 秒级时间戳。 |
|
||
| `status` | string | `completed`、`failed` 或 `incomplete`。 |
|
||
| `model` | string | 实际使用模型。 |
|
||
| `output[]` | array | 输出 item。当前仅返回 message。 |
|
||
| `output[].content[].type` | string | 当前仅返回 `output_text`。 |
|
||
| `usage` | object | token 用量。 |
|
||
| `incomplete_details` | object 或 null | `status:"incomplete"` 时说明原因。 |
|
||
|
||
### Responses 流式事件
|
||
|
||
`stream=true` 时返回 SSE，使用 `event:` + `data:` 双行格式。
|
||
|
||
事件类型:
|
||
|
||
| 事件 | 含义 |
|
||
|------|------|
|
||
| `response.created` | Response 已创建。 |
|
||
| `response.in_progress` | 开始处理。 |
|
||
| `response.output_item.added` | 新增 message item。 |
|
||
| `response.content_part.added` | 新增 output_text part。 |
|
||
| `response.output_text.delta` | 文本增量。 |
|
||
| `response.output_text.done` | 当前 output_text 完成。 |
|
||
| `response.content_part.done` | 当前 part 完成。 |
|
||
| `response.output_item.done` | 当前 item 完成。 |
|
||
| `response.completed` | 整体完成，携带完整 response 和 usage。 |
|
||
|
||
示例:
|
||
|
||
```text
|
||
event: response.output_text.delta
|
||
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":"# 文本"}
|
||
```
|
||
|
||
### 不支持的 Responses 参数
|
||
|
||
- `tools`、`tool_choice`、`parallel_tool_calls`、`max_tool_calls`
|
||
- `background`
|
||
- `conversation`、`previous_response_id`
|
||
- `include`、`prompt`、`top_logprobs`、`text`、`truncation`、`context_management`
|
||
- `metadata`、`safety_identifier`、`prompt_cache_key`、`prompt_cache_retention`、`user`、`service_tier`
|
||
|
||
Responses 错误:
|
||
|
||
| HTTP | code | 场景 |
|
||
|------|------|------|
|
||
| 400 | `invalid_request` | input 结构非法、role 不支持、缺少模型等。 |
|
||
| 400 | `unsupported_parameter` | `store=true` 或其他不支持参数。 |
|
||
| 404 | `model_not_found` | 模型不存在。 |
|
||
| 413 | `content_too_large` | 输入超过限制。 |
|
||
| 429 | `rate_limit_exceeded` | 触发 chat 类限流。 |
|
||
| 503 | `service_unavailable` | 模型服务不可用。 |
|
||
|
||
## 本地 Server 差异
|
||
|
||
Local Parse Server 可以暴露同样的 Chat 和 Responses endpoint，但实际可用模型取决于本地 `GET /v1/models`。
|
||
|
||
本地实现约束:
|
||
|
||
- 如果没有可服务的 VLM 或指定模型，应返回 `404 model_not_found` 或 `503 service_unavailable`。
|
||
- 不得静默切换到 `flash`。
|
||
- 本地部署通常不做 anonymous/registered 的功能售卖差异；启用 API Key 后，通过认证的请求可以使用本地 server 暴露的全部模型能力。
|
||
- 如果本地不实现 Chat/Responses，应在 `GET /v1/models` 中不要暴露对应模型，并对 endpoint 返回明确错误。
|
||
|
||
这里的 Chat/Responses 为独立协议说明；Python 解析服务不新增这些路由。独立 Uploads 移除后，图片输入使用 URL 或 data URI，不再承诺 purpose=input_image 的 File 输入。
|