ThinkParse

https://github.com/wzdavid/thinkparse
Admin
ThinkParse is an enterprise document parsing system that converts complex documents like PDFs and...
Tokens:70,598
Snippets:429
Trust Score:7.3
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start ThinkParse with Docker Compose

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/quickstart.zh.md

Validates the compose configuration and starts the services in detached mode with build. The first build downloads models and may take a long time; `up` waits for MinerU health (start_period up to ~600s) before starting the gateway.

```bash
docker compose --env-file .env -f docker/docker-compose.yml config --services
docker compose --env-file .env -f docker/docker-compose.yml up -d --build
```

--------------------------------

### GET /api/v1/queue/tasks

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取队列中的任务列表。

```APIDOC
## GET /api/v1/queue/tasks

### Description
获取队列中的任务列表。返回 tasks[] 数组，包含 task_id、status、file_name。

### Method
GET

### Endpoint
/api/v1/queue/tasks

### Response
#### Success Response (200)
- **tasks** (array) - 任务列表
  - **task_id** (string) - 任务 ID
  - **status** (string) - 状态
  - **file_name** (string) - 文件名
```

--------------------------------

### GET /api/v1/health/ready

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

检查服务是否就绪。

```APIDOC
## GET /api/v1/health/ready

### Description
检查服务是否就绪。任务库、对象存储、至少一个 MinerU 健康时返回 200，否则 503。

### Method
GET

### Endpoint
/api/v1/health/ready

### Response
#### Success Response (200)
- 无特定字段

#### Error Responses
- **503** - 服务未就绪
```

--------------------------------

### GET /api/v1/health/live

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

检查网关进程存活。

```APIDOC
## GET /api/v1/health/live

### Description
检查网关进程是否存活。

### Method
GET

### Endpoint
/api/v1/health/live

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v2/tiers

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Lists the processing tiers available in this installation. Does not expose MinerU model repository names.

```APIDOC
## GET /api/v2/tiers

### Description
Lists the processing tiers available in this installation. Does not expose MinerU model repository names.

### Method
GET

### Endpoint
/api/v2/tiers

### Response
#### Success Response (200)
- **data** (array) - List of tier objects.
  - **id** (string) - Tier identifier.
- **discovered** (boolean) - Whether tiers were discovered dynamically.

#### Response Example
{
  "data": [
    {
      "id": "standard"
    }
  ],
  "discovered": true
}

```

--------------------------------

### GET /api/v2/jobs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取任务列表。

```APIDOC
## GET /api/v2/jobs

### Description
获取任务列表，支持按状态和数量过滤。

### Method
GET

### Endpoint
/api/v2/jobs

### Parameters
#### Query Parameters
- **status** (string) - Optional - 任务状态
- **limit** (integer) - Optional - 返回数量限制

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v1/queue/stats

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取队列统计信息。

```APIDOC
## GET /api/v1/queue/stats

### Description
获取队列统计信息。返回 stats.pending、stats.processing 等字段。

### Method
GET

### Endpoint
/api/v1/queue/stats

### Response
#### Success Response (200)
- **stats** (object) - 队列统计
  - **pending** (integer) - 等待中的任务数
  - **processing** (integer) - 处理中的任务数
```

--------------------------------

### Two-GPU .env configuration

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Example .env settings for a two-GPU deployment. THINKPARSE_SLOTS must be a comma-separated list with one entry per MinerU address, each equal to MINERU_GPU_CONCURRENCY.

```bash
COMPOSE_PROFILES=gpu,gpu1
MINERU_BASE_URLS=http://mineru-gpu0:8002,http://mineru-gpu1:8002
MINERU_GPU_CONCURRENCY=2
THINKPARSE_SLOTS=2,2
```

--------------------------------

### GET /api/v2/jobs/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取任务详情。

```APIDOC
## GET /api/v2/jobs/{id}

### Description
获取任务详情，包含 timing、attempt、pages、batch_id、priority 等字段。

### Method
GET

### Endpoint
/api/v2/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 任务 ID

### Response
#### Success Response (200)
- **timing** (object) - 时间统计
  - **queue_ms** (integer) - 排队耗时（毫秒）
  - **parse_ms** (integer) - 解析耗时（毫秒）
  - **project_ms** (integer) - 投影耗时（毫秒）
- **attempt** (integer) - 尝试次数
- **pages** (integer) - 页数
- **batch_id** (string) - 批次 ID
- **priority** (integer) - 优先级
```

--------------------------------

### GET /api/v2/tiers

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取可用档位列表。

```APIDOC
## GET /api/v2/tiers

### Description
获取可用档位列表。返回 data[].id 与 discovered。

### Method
GET

### Endpoint
/api/v2/tiers

### Response
#### Success Response (200)
- **data** (array) - 档位列表
  - **id** (string) - 档位 ID
  - **discovered** (boolean) - 是否发现
```

--------------------------------

### GET /api/v2/files/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取文件信息。

```APIDOC
## GET /api/v2/files/{id}

### Description
获取文件信息。

### Method
GET

### Endpoint
/api/v2/files/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 文件 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v1/health/deep

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取上游详情、在途等运维信息。

```APIDOC
## GET /api/v1/health/deep

### Description
获取上游详情、在途等运维信息。

### Method
GET

### Endpoint
/api/v1/health/deep

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v2/batches/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取批次信息。

```APIDOC
## GET /api/v2/batches/{id}

### Description
获取批次信息。

### Method
GET

### Endpoint
/api/v2/batches/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 批次 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v1/tasks/{task_id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

查询任务状态，返回任务详情和完成时的解析结果。

```APIDOC
## GET /api/v1/tasks/{task_id}

### Description
查询任务状态。返回任务详情，包括状态、文件名、后端等。任务完成时顶层包含 markdown_content、content_list、middle_json、images 等字段。

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - 任务 ID

### Response
#### Success Response (200)
- **success** (boolean) - 固定为 true
- **task** (object) - 任务详情
  - **task_id** (string) - 任务 ID
  - **status** (string) - 状态：pending、processing、completed、failed、cancelled
  - **file_name** (string) - 文件名
  - **backend** (string) - 后端标识
  - **error_message** (string|null) - 错误信息，失败时非空
  - **started_at** (string|null) - 开始时间
  - **completed_at** (string|null) - 完成时间
- **markdown_content** (string) - 完成时存在，Markdown 内容
- **content_list** (array) - 完成时存在，内容列表
- **middle_json** (object) - 完成时存在，中间 JSON
- **images** (array) - 完成时存在，图片数组
- **data.content** (string) - 完成时存在，与 markdown_content 相同

#### Response Example
{
  "success": true,
  "task": {
    "task_id": "...",
    "status": "pending",
    "file_name": "paper.pdf",
    "backend": "pipeline",
    "error_message": null,
    "started_at": null,
    "completed_at": null
  }
}

#### Error Responses
- **404** - 未知任务
```

--------------------------------

### GET /api/v2/batches/{id}/jobs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取批次下的任务列表。

```APIDOC
## GET /api/v2/batches/{id}/jobs

### Description
获取批次下的任务列表。

### Method
GET

### Endpoint
/api/v2/batches/{id}/jobs

### Parameters
#### Path Parameters
- **id** (string) - Required - 批次 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v2/stats

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取统计信息。

```APIDOC
## GET /api/v2/stats

### Description
获取统计信息，包括队列、槽位、在途字节、时间窗内完成数等。通常需要 API key。

### Method
GET

### Endpoint
/api/v2/stats

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v2/health

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

检查服务健康状态。

```APIDOC
## GET /api/v2/health

### Description
检查服务健康状态。任务库、对象存储、每个上游健康与档位；任一 MinerU 可达即 200。可不带 key，适合负载均衡探活。

### Method
GET

### Endpoint
/api/v2/health

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v2/uploads/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取上传会话信息。

```APIDOC
## GET /api/v2/uploads/{id}

### Description
获取上传会话信息。

### Method
GET

### Endpoint
/api/v2/uploads/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 上传会话 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v1/health

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

General health endpoint. Behavior not explicitly detailed in source.

```APIDOC
## GET /api/v1/health

### Description
General health endpoint. Behavior not explicitly detailed in source.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
None

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- (No specific fields documented)

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### GET /api/v2/files/{id}/content

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

获取文件内容。

```APIDOC
## GET /api/v2/files/{id}/content

### Description
获取文件内容。

### Method
GET

### Endpoint
/api/v2/files/{id}/content

### Parameters
#### Path Parameters
- **id** (string) - Required - 文件 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### GET /api/v1/health/live

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Health check that only indicates the gateway process is alive.

```APIDOC
## GET /api/v1/health/live

### Description
Health check that only indicates the gateway process is alive.

### Method
GET

### Endpoint
/api/v1/health/live

### Parameters
None

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- (No specific fields documented)

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### GET /api/v1/health/ready

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Health check that returns 200 when task database, object storage, and MinerU /v1/health are all available; otherwise 503.

```APIDOC
## GET /api/v1/health/ready

### Description
Health check that returns 200 when task database, object storage, and MinerU /v1/health are all available; otherwise 503.

### Method
GET

### Endpoint
/api/v1/health/ready

### Parameters
None

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- (No specific fields documented)

#### Error Responses
- **503** - Service unavailable.

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### GET /api/v2/stats

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Returns current queue length, slots, in-flight bytes, and completion count for a recent time window. Requires API key.

```APIDOC
## GET /api/v2/stats

### Description
Returns current queue length, slots, in-flight bytes, and completion count for a recent time window. Requires API key.

### Method
GET

### Endpoint
/api/v2/stats

### Authentication
- **Authorization** (header) - Required - Bearer token.

### Response
#### Success Response (200)
- **queue** (integer) - Current queue length.
- **slots** (integer) - Available slots.
- **in_flight_bytes** (integer) - Bytes currently in flight.
- **completed_recent** (integer) - Number of completions in the recent time window.

#### Response Example
{
  "queue": 5,
  "slots": 10,
  "in_flight_bytes": 1024,
  "completed_recent": 100
}

```

--------------------------------

### POST /file_parse

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Legacy endpoint that creates a task and waits for its completion, then returns the same JSON as GET /api/v1/tasks/{id}. New integrations should not use this endpoint.

```APIDOC
## POST /file_parse

### Description
Legacy endpoint that creates a task and waits for its completion, then returns the same JSON as GET /api/v1/tasks/{id}. New integrations should not use this endpoint.

### Method
POST

### Endpoint
/file_parse

### Parameters
#### Request Body (multipart/form-data)
- **file** (file) - Required - The file to be parsed.
- Other form fields as described in section 5 (legacy mapping).

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
Same JSON structure as GET /api/v1/tasks/{id}.

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### GET /api/v2/jobs/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Retrieves the status and details of a specific job, including timing, attempt, pages, and batch_id.

```APIDOC
## GET /api/v2/jobs/{id}

### Description
Retrieves the status and details of a specific job, including timing, attempt, pages, and batch_id.

### Method
GET

### Endpoint
/api/v2/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The job identifier.

### Response
#### Success Response (200)
- **id** (string) - Job identifier.
- **status** (string) - Job status.
- **timing** (object) - Timing details.
  - **queue_ms** (integer) - Time spent in queue.
  - **parse_ms** (integer) - Time spent parsing.
  - **project_ms** (integer) - Time spent projecting.
- **attempt** (integer) - Current attempt number.
- **pages** (integer) - Number of pages processed.
- **batch_id** (string) - Associated batch identifier.

#### Response Example
{
  "id": "job-id",
  "status": "completed",
  "timing": {
    "queue_ms": 100,
    "parse_ms": 500,
    "project_ms": 200
  },
  "attempt": 1,
  "pages": 10,
  "batch_id": "batch-id"
}

```

--------------------------------

### GET /api/v1/queue/stats

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Returns queue statistics. Pending and processing counts come from the task database; completed and failed counts are real counts.

```APIDOC
## GET /api/v1/queue/stats

### Description
Returns queue statistics. Pending and processing counts come from the task database; completed and failed counts are real counts.

### Method
GET

### Endpoint
/api/v1/queue/stats

### Parameters
None

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- **stats** (object) - Contains:
  - **pending** (integer) - Number of pending tasks.
  - **processing** (integer) - Number of processing tasks.
  - **completed** (integer) - Number of completed tasks.
  - **failed** (integer) - Number of failed tasks.

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### GET /api/v2/health

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Returns health status of the task database, object storage, each MinerU instance, current tiers, and in-flight count. Returns 200 if any MinerU is reachable. Does not require API key, for load balancer health checks.

```APIDOC
## GET /api/v2/health

### Description
Returns health status of the task database, object storage, each MinerU instance, current tiers, and in-flight count. Returns 200 if any MinerU is reachable. Does not require API key, for load balancer health checks.

### Method
GET

### Endpoint
/api/v2/health

### Response
#### Success Response (200)
- **database** (string) - Health status of the task database.
- **storage** (string) - Health status of object storage.
- **mineru** (array) - Health status of each MinerU instance.
- **tiers** (array) - Current available tiers.
- **in_flight** (integer) - Number of in-flight jobs.

#### Response Example
{
  "database": "ok",
  "storage": "ok",
  "mineru": ["ok"],
  "tiers": ["standard"],
  "in_flight": 3
}

```

--------------------------------

### GET /api/v1/health/deep

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Health check that provides per-GPU worker details, in-flight counts, and last projection failure. For operational use only.

```APIDOC
## GET /api/v1/health/deep

### Description
Health check that provides per-GPU worker details, in-flight counts, and last projection failure. For operational use only.

### Method
GET

### Endpoint
/api/v1/health/deep

### Parameters
None

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- (No specific fields documented)

#### Response Example
(No explicit example provided in source)

```

--------------------------------

### Clone repository and copy .env.example

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/quickstart.zh.md

Clones the ThinkParse repository, enters the directory, and copies the environment template to .env. Required before editing configuration.

```bash
git clone https://github.com/wzdavid/ThinkParse.git
cd ThinkParse
cp .env.example .env
```

--------------------------------

### 快速开始：克隆、配置与启动

Source: https://github.com/wzdavid/thinkparse/blob/main/README.zh.md

快速启动 ThinkParse 的完整命令序列：克隆仓库、配置环境变量、按需选择 COMPOSE_PROFILES（gpu 或 cpu），启动容器并验证健康检查与档位接口。

```bash
git clone https://github.com/wzdavid/ThinkParse.git
cd ThinkParse
cp .env.example .env
# 三选一：COMPOSE_PROFILES=gpu | cpu | （留空接外部 MinerU）
# 修改 POSTGRES_PASSWORD、MINIO_ROOT_USER、MINIO_ROOT_PASSWORD

docker compose --env-file .env -f docker/docker-compose.yml up -d --build
curl -fsS http://127.0.0.1:8000/api/v1/health/live
curl -sS http://127.0.0.1:8000/api/v1/health/ready
curl -sS http://127.0.0.1:8000/api/v2/tiers

```

--------------------------------

### 验证命令（unittest）

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0_PLAN.zh.md

运行控制面测试的命令。

```bash
cd /Users/david/Blue/ThinkParse
PYTHONPATH=. python -m unittest discover -s tests -p 'test_control_*.py'
```

--------------------------------

### Record resource baseline with nvidia-smi, free, and /api/v1/health/deep

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Record resource baseline while one task is in flight, including GPU memory and utilization, free memory, and the deep health endpoint.

```bash
nvidia-smi --query-gpu=index,memory.used,utilization.gpu --format=csv
free -h
curl -sS http://127.0.0.1:8000/api/v1/health/deep
```

--------------------------------

### Verify health and tiers endpoints

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/quickstart.zh.md

Checks service readiness: live returns HTTP 200, ready returns 200 when MinerU is reachable with components.task_store and components.object_store true, and tiers shows discovered: true with a list matching the selected mode.

```bash
curl -fsS http://127.0.0.1:8000/api/v1/health/live
curl -sS http://127.0.0.1:8000/api/v1/health/ready
curl -sS http://127.0.0.1:8000/api/v2/tiers
```

--------------------------------

### 开发：安装依赖、运行测试与检查

Source: https://github.com/wzdavid/thinkparse/blob/main/README.zh.md

开发环境安装依赖并运行测试与代码检查。

```bash
pip install -r control/requirements-dev.txt
PYTHONPATH=. python -m unittest discover -s tests -p 'test_control_*.py'
ruff check control tests

```

--------------------------------

### 查看日志并停止服务

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

查看 gateway、reconciler 和 mineru-gpu 的实时日志，然后停止服务但保留卷；使用 down -v 会删除任务与产物。

```bash
docker compose --env-file .env -f docker/docker-compose.yml logs -f gateway reconciler mineru-gpu
docker compose --env-file .env -f docker/docker-compose.yml down      # 保留卷
# down -v 会删除任务与产物
```

--------------------------------

### Check services and query /api/v2/tiers

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Check running services and query the tier endpoint. discovered: true means tiers were read from upstream; false means upstream is not reachable yet and the list only shows configured allowed values.

```bash
docker compose --env-file .env -f docker/docker-compose.yml ps
```

```bash
curl -sS http://127.0.0.1:8000/api/v2/tiers
```

--------------------------------

### 异步提交任务：curl 命令

Source: https://github.com/wzdavid/thinkparse/blob/main/README.zh.md

异步提交 PDF 文档到 /api/v1/tasks/submit，使用 pipeline 后端。适用于批量与生产场景。

```bash
curl -sS \
  -F "file=@document.pdf" \
  -F "backend=pipeline" \
  http://127.0.0.1:8000/api/v1/tasks/submit

```

--------------------------------

### Health check with curl for /api/v1/health/live and /api/v1/health/ready

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Check the live and ready health endpoints. The live endpoint should return 200, and the ready endpoint returns 200 when MinerU is reachable, otherwise 503. In both cases, components.task_store and components.object_store should be true; do not submit jobs when components.mineru is false.

```bash
curl -fsS http://127.0.0.1:8000/api/v1/health/live
curl -sS -D - http://127.0.0.1:8000/api/v1/health/ready -o /tmp/thinkparse-ready.json
cat /tmp/thinkparse-ready.json
```

--------------------------------

### POST /api/v2/uploads

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Creates a new upload resource, registering byte count and checksum before content is uploaded.

```APIDOC
## POST /api/v2/uploads

### Description
Creates a new upload resource, registering byte count and checksum before content is uploaded.

### Method
POST

### Endpoint
/api/v2/uploads

### Parameters
#### Request Body
- **byte_count** (integer) - Required - The number of bytes in the file to be uploaded.
- **checksum** (string) - Required - The SHA-256 checksum of the file content.

### Request Example
{
  "byte_count": 12345,
  "checksum": "sha256hex..."
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created upload resource.

#### Response Example
{
  "id": "upload-id"
}

```

--------------------------------

### Submit PDF task

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/quickstart.zh.md

Submits a PDF file for processing using the pipeline backend, which maps to MinerU basic tier. The response contains a task_id to use for polling.

```bash
curl -sS \
  -F "file=@tests/files/2604.04771v2.pdf" \
  -F "backend=pipeline" \
  http://127.0.0.1:8000/api/v1/tasks/submit
```

--------------------------------

### POST /api/v2/jobs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

创建解析任务。

```APIDOC
## POST /api/v2/jobs

### Description
创建解析任务。body 含 file_id（或 MinerU 风格的 files[].source.file_id），可选 tier、ocr_mode、batch_id、priority。

### Method
POST

### Endpoint
/api/v2/jobs

### Parameters
#### Request Body
- **file_id** (string) - Required - 文件 ID
- **files[].source.file_id** (string) - Optional - MinerU 风格的文件引用
- **tier** (string) - Optional - 档位
- **ocr_mode** (string) - Optional - OCR 模式
- **batch_id** (string) - Optional - 批次 ID，字母、数字、-、_，最长 64
- **priority** (integer) - Optional - 优先级，0-9，越大越优先

### Response
#### Success Response (202)
- 无特定字段

#### Error Responses
- **400** - 部署做不到的档位直接返回 400
```

--------------------------------

### GET /api/v2/jobs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Lists jobs, optionally filtered by status and limited by count.

```APIDOC
## GET /api/v2/jobs

### Description
Lists jobs, optionally filtered by status and limited by count.

### Method
GET

### Endpoint
/api/v2/jobs

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by job status.
- **limit** (integer) - Optional - Maximum number of jobs to return.

### Response
#### Success Response (200)
- **jobs** (array) - List of job objects.
  - **id** (string) - Job identifier.
  - **status** (string) - Job status.

#### Response Example
{
  "jobs": [
    {
      "id": "job-id",
      "status": "queued"
    }
  ]
}

```

--------------------------------

### GET /api/v1/tasks/{task_id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Retrieves the status and result of a task. Returns a task object with status and, when completed, the parsed content fields.

```APIDOC
## GET /api/v1/tasks/{task_id}

### Description
Retrieves the status and result of a task. Returns a task object with status and, when completed, the parsed content fields.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the task.

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- **success** (boolean) - Always true.
- **task** (object) - Contains task details.
  - **task_id** (string) - Task ID.
  - **status** (string) - One of: pending, processing, completed, failed, cancelled.
  - **file_name** (string) - Name of the file.
  - **backend** (string) - Backend used.
  - **error_message** (string|null) - Error message if failed, otherwise null.
  - **started_at** (string|null) - Start timestamp.
  - **completed_at** (string|null) - Completion timestamp.
- When status is completed, additional top-level fields:
  - **markdown_content** (string) - Markdown content with relative image paths.
  - **content_list** (array) - Array of objects with fields: type, text, page_idx, text_level, bbox, table and image fields.
  - **middle_json** (object) - Contains pdf_info array; each page has page_size and discarded_blocks.
  - **images** (array) - Array of image filenames; empty array if no images.
  - **data.content** (string) - Same as markdown_content.

#### Response Example (In Progress)
```json
{
  "success": true,
  "task": {
    "task_id": "...",
    "status": "pending",
    "file_name": "paper.pdf",
    "backend": "pipeline",
    "error_message": null,
    "started_at": null,
    "completed_at": null
  }
}
```

#### Error Responses
- **404** - Unknown task.

```

--------------------------------

### POST /api/v2/uploads/{id}/complete

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

完成上传会话。

```APIDOC
## POST /api/v2/uploads/{id}/complete

### Description
完成上传会话。

### Method
POST

### Endpoint
/api/v2/uploads/{id}/complete

### Parameters
#### Path Parameters
- **id** (string) - Required - 上传会话 ID

### Response
#### Success Response (202)
- 无特定字段
```

--------------------------------

### View gateway and reconciler logs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/quickstart.zh.md

Follows logs for the gateway and reconciler containers, useful for diagnosing issues like tasks stuck in processing or tiers not discovered.

```bash
docker compose --env-file .env -f docker/docker-compose.yml logs -f gateway reconciler
```

--------------------------------

### POST /api/v2/uploads

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

创建上传会话。

```APIDOC
## POST /api/v2/uploads

### Description
创建上传会话。

### Method
POST

### Endpoint
/api/v2/uploads

### Response
#### Success Response (202)
- 无特定字段
```

--------------------------------

### 代码结构（control/ 目录）

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0_PLAN.zh.md

列出 2.0 控制面的主要文件和目录结构。

```text
control/                 2.0 控制面，不加载 CUDA
  gateway.py             /api/v1 兼容与 /api/v2 产品接口。MinerU /v1 只在协调器内部调用
  reconciler.py          独立进程入口
  reconcile.py           投递、轮询、重试、取消、投影、超时、清理
  mineru.py              MinerU 4.0 HTTP
  docling.py             docling-serve HTTP，只接非 PDF
  project.py             MinerU middle → 3.x 形状；Docling 保留 docling_document
  store.py               PostgreSQL 与内存任务库
  objects.py             本地目录；设置 endpoint 后走外部 S3
docker/docker-compose.yml    cpu 与 gpu 两个 profile，别名都是 mineru-router
docker/mineru.Dockerfile      GPU，默认下载 standard
docker/mineru-cpu.Dockerfile  CPU，ONNX basic
tests/test_control_*.py
tests/fixtures/legacy_projection/
```

--------------------------------

### POST /api/v1/tasks/submit

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

提交一个新的解析任务，使用 multipart/form-data 上传文件，可选 priority 参数控制优先级。

```APIDOC
## POST /api/v1/tasks/submit

### Description
提交一个新的解析任务。请求为 multipart/form-data，文件字段名为 file。可选表单 priority 控制优先级（0-9，越大越优先，默认 0）。

### Method
POST

### Endpoint
/api/v1/tasks/submit

### Parameters
#### Request Body
- **file** (file) - Required - 要解析的文件
- **priority** (integer) - Optional - 优先级，0-9，越大越优先，默认 0。超出范围返回 400。

### Response
#### Success Response (200)
- **success** (boolean) - 固定为 true
- **task_id** (string) - ThinkParse 生成的任务 ID
- **status** (string) - 固定为 "pending"
- **file_name** (string) - 文件名
- **created_at** (string) - 创建时间
- **backend** (string) - 后端标识
- **priority** (integer) - 优先级

#### Response Example
{
  "success": true,
  "task_id": "...",
  "status": "pending",
  "file_name": "paper.pdf",
  "created_at": "...",
  "backend": "pipeline",
  "priority": 0
}

#### Error Responses
- **400** - priority 超出范围
- **413** - 文件过大
- **507** - 本地对象目录水位不足（外部 S3 不做此项检查）
```

--------------------------------

### ThinkParse 架构图

Source: https://github.com/wzdavid/thinkparse/blob/main/README.zh.md

展示 ThinkParse 的整体架构：客户端通过 /api/v1 或 /api/v2 提交任务，API 与任务编排层处理后，通过 HTTP 将任务分发到 MinerU 4.0 或 Docling Serve。

```text
你的应用
   │  POST /api/v1/tasks/submit   或   /api/v2/uploads + /api/v2/jobs
   ▼
┌──────────────────────────────────────────────┐
│ ThinkParse（API + 任务编排）                    │
│  网关 · PostgreSQL · 对象存储 · 协调循环         │
└──────────────────┬───────────────────────────┘
                   │ HTTP
        ┌──────────┴──────────┐
        ▼                     ▼
  MinerU 4.0（多 GPU）      Docling Serve（可选）

```

--------------------------------

### POST /api/v2/uploads/{id}/complete

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Marks an upload as complete, allowing a job to be created referencing the file.

```APIDOC
## POST /api/v2/uploads/{id}/complete

### Description
Marks an upload as complete, allowing a job to be created referencing the file.

### Method
POST

### Endpoint
/api/v2/uploads/{id}/complete

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the upload resource.

### Response
#### Success Response (200)
- **status** (string) - Confirmation that the upload is complete.

#### Response Example
{
  "status": "complete"
}

```

--------------------------------

### POST /api/v2/jobs

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Creates a new parsing job. Accepts a file_id or MinerU-style files[].source.file_id, and optionally a batch_id. Returns 202 Accepted.

```APIDOC
## POST /api/v2/jobs

### Description
Creates a new parsing job. Accepts a file_id or MinerU-style files[].source.file_id, and optionally a batch_id. Returns 202 Accepted.

### Method
POST

### Endpoint
/api/v2/jobs

### Parameters
#### Request Body
- **file_id** (string) - Optional - The identifier of the uploaded file to parse.
- **files** (array) - Optional - MinerU-style file references.
  - **source.file_id** (string) - Required - The file identifier.
- **batch_id** (string) - Optional - Identifier of a batch to associate the job with.
- **tier** (string) - Required - The processing tier (e.g., standard, premium).
- **ocr_mode** (string) - Required - The OCR mode to use.

### Request Example
{
  "file_id": "file-id",
  "batch_id": "batch-id",
  "tier": "standard",
  "ocr_mode": "auto"
}

### Response
#### Success Response (202)
- **id** (string) - The job identifier.
- **status** (string) - Initial status, e.g., "queued".

#### Response Example
{
  "id": "job-id",
  "status": "queued"
}

```

--------------------------------

### Save markdown content to file with python3 one-liner

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Save the markdown_content from the task response to /tmp/thinkparse-result.md for reading instead of verification.

```bash
python3 -c 'import json; from pathlib import Path; body=json.loads(Path("/tmp/thinkparse-task.json").read_text()); Path("/tmp/thinkparse-result.md").write_text(body["markdown_content"])'
```

--------------------------------

### Summarize task response with python3 heredoc

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/DEPLOYMENT.zh.md

Print a summary of the completed task response without opening the large file directly. It reports status, error_message, page count, page_size, schema_key, equation and table counts, markdown length and equality with data.content, data:image occurrences, image metadata, and the sample header. The script intentionally does not print data_url values.

```bash
python3 - <<'PY'
import json
from pathlib import Path

body = json.loads(Path("/tmp/thinkparse-task.json").read_text())
task = body["task"]
middle = body.get("middle_json") or {}
info = middle.get("pdf_info") or []
content = body.get("content_list") or []
images = body.get("images") or []
markdown = body.get("markdown_content") or ""
equations = [item for item in content if item.get("type") == "equation" and item.get("text")]
tables = [item for item in content if item.get("type") == "table" and "<table" in (item.get("table_body") or "")]
header = ""
for page in info:
    for block in page.get("discarded_blocks") or []:
        for line in block.get("lines") or []:
            for span in line.get("spans") or []:
                text = span.get("content") or ""
                if "2604.04771" in text:
                    header = text
print("status", task.get("status"))
print("error_message", task.get("error_message"))
print("pages", len(info), "page_size", info[0].get("page_size") if info else None)
print("schema_key", "schema" in middle)
print("equations", len(equations), "html_tables", len(tables))
print("markdown_chars", len(markdown), "same_as_data.content", markdown == (body.get("data") or {}).get("content"))
print("data_image_in_markdown", markdown.count("data:image"))
print("images", len(images), "first", None if not images else {k: images[0][k] for k in ("filename", "mime_type", "size_bytes")})
print("header", header or "(样例页眉未找到)")
PY
```

--------------------------------

### PUT /api/v2/uploads/{id}/content

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

上传文件内容。

```APIDOC
## PUT /api/v2/uploads/{id}/content

### Description
上传文件内容。

### Method
PUT

### Endpoint
/api/v2/uploads/{id}/content

### Parameters
#### Path Parameters
- **id** (string) - Required - 上传会话 ID

### Response
#### Success Response (202)
- 无特定字段
```

--------------------------------

### POST /api/v1/tasks/submit

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/design/THINKPARSE_2.0.zh.md

Submits a new parsing task. Accepts multipart/form-data with a file field named 'file'. Returns a task ID and initial status. This endpoint is the primary submission path for the v1 API.

```APIDOC
## POST /api/v1/tasks/submit

### Description
Submits a new parsing task. Accepts multipart/form-data with a file field named 'file'. Returns a task ID and initial status.

### Method
POST

### Endpoint
/api/v1/tasks/submit

### Parameters
#### Request Body (multipart/form-data)
- **file** (file) - Required - The file to be parsed.
- **backend** (string) - Optional - Legacy field; if omitted or set to 'pipeline', maps to tier=basic. Unknown values return 400.
- **method** (string) - Optional - Legacy field; maps to ocr_mode. Allowed values: auto, txt, ocr.
- **lang** (string) - Optional - Language passed to MinerU.
- **formula_enable** (boolean) - Optional - If false, disables formula processing in basic tier.
- **table_enable** (boolean) - Optional - If false, disables table processing; if engine doesn't support, warning is recorded.
- **f_dump_content_list** (boolean) - Optional - Ignored; response always includes content_list.
- **enable_pagination** (boolean) - Optional - Accepted but has no effect.
- **tier** (string) - Optional - New field: flash, basic, standard, advanced. Only explicit values are accepted; unknown values return 400.

### Request Example
(No explicit example provided in source)

### Response
#### Success Response (200)
- **success** (boolean) - Always true.
- **task_id** (string) - Non-empty string, generated by ThinkParse.
- **status** (string) - Always "pending".
- **file_name** (string) - Name of the submitted file.
- **created_at** (string) - Timestamp of creation.
- **backend** (string) - The backend used (e.g., "pipeline").

#### Response Example
(No explicit example provided in source)

#### Error Responses
- **413** - File too large.
- **507** - Insufficient disk or object storage capacity.
- **400** - Unknown backend or tier value.

```

--------------------------------

### DELETE /api/v2/batches/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

取消该批未终态任务。

```APIDOC
## DELETE /api/v2/batches/{id}

### Description
取消该批未终态任务。

### Method
DELETE

### Endpoint
/api/v2/batches/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 批次 ID

### Response
#### Success Response (200)
- 无特定字段
```

--------------------------------

### DELETE /api/v2/jobs/{id}

Source: https://github.com/wzdavid/thinkparse/blob/main/docs/api.zh.md

取消任务。

```APIDOC
## DELETE /api/v2/jobs/{id}

### Description
取消任务。ThinkParse 任务号，引擎重启后仍有效。

### Method
DELETE

### Endpoint
/api/v2/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - 任务 ID

### Response
#### Success Response (200)
- 无特定字段
```
Tokens:
Raw