可配置的多模型文档 VLM 应用:统一任务接口,兼容 OvisOCR 2/3、HunyuanOCR、DotsOCR/DotsMOCR 等;支持并发、结构化日志、内置/外接 vLLM 与简易 Web 界面。
协作约定见 AGENTS.md(Python 包 docvlm,CLI docvlm)。
Prompt 对照:OvisOCR3 · DotsMOCR · DotsOCR · MiniCPM-OCR(各 docvlm/prompts/<model>/{task_id}.py 导出 PROMPT)。
任务 API 与 data 字段:docs/api/tasks.md · GET /api/schema · Swagger /docs。
- 多模型目录、单模型运行:可在 YAML 中配置多个
models.*,但同一时刻只激活一个(见下节);切换模型后任务列表按该模型 Processor 能力过滤。 - 多任务、接口一致:multipart 单图;分组
parse/general(见 docs/api/tasks.md)。 - vLLM:
internal子进程 + 日志 + 出错重启;external连已有 OpenAI 兼容服务;模式与 Base URL 仅配置文件/环境变量;Web UI 只读展示连接状态,可切换当前models.*键。 - 配置:
config/app.yaml+config/models.yaml(default+ 各模型键)+config/tasks.yaml+ 环境变量DOCVLM_*。 - 运维:任务并发上限、structlog、健康检查、简易静态前端。
DocVLM 面向多模型族(Ovis、混元、Dots 等可在同一套配置里并存),但运行时同一进程只服务一个当前模型,与「一次激活一个模型 + 只开放该模型支持的任务」的产品语义一致。
| 维度 | 说明 |
|---|---|
| 配置层 | models 下可写多条(deploy.model_path、deploy.served_name 等);用于模型清单、切换目标、按 key 合并 deploy/invoke 默认。 |
| 运行层 | 同一时刻仅一个当前模型键(vllm.model / model_name 解析结果);Processor、任务列表、LiteLLM model(served_name)均对应该键。 |
| 切换 | 配置:改 vllm.model_name 或 models 默认键后重启。运行时:POST /api/vllm/switch-model({"model":"<配置键>"})或 Web UI 模型下拉;internal 会重启子进程加载权重。切换成功要求目标模型在 vLLM 上可用(/v1/models 含 served_name),否则回滚;推理前不可用返回 503。 |
| 任务 | 各模型 Processor.supported_tasks 不同(如 OvisOCR2 仅部分任务);非当前模型支持的任务在 /api/tasks 中不出现,直调 API 返回 400。 |
| 并发 | 多请求可并行,但都打在同一当前模型上,受 app.max_concurrent_tasks 限制。 |
不会在单个 DocVLM 进程内同时为多个 models.* 各起一套 vLLM 并路由;若需多模型并行在线,请部署多实例或自行在外部起多个 vLLM,各模型在 models.yaml 中配置 mode=external 与各自 base_url / model_name。
| 配置键 | 说明 |
|---|---|
ovisocr2 / ovisocr3 |
Ovis OCR 2/3 |
hunyuanocr |
混元 OCR |
dotsocr / dotsmocr |
Dots OCR / MOCR |
minicpmocr |
MiniCPM-OCR 1.0 |
在 config/app.yaml 中修改 vllm.model_name、base_url / api_key / timeout_seconds、vllm.invoke 与 vllm.internal.deploy;各模型的 Hugging Face 地址见配置文件内注释。
| 分组 | 说明 | 任务 id |
|---|---|---|
parse |
文档解析 | end2end, dla_text, dla |
general |
通用 OCR | table, chart, formula, ocr, image, ocr_bbox |
示例:POST /api/parse/end2end、POST /api/general/ocr。响应字段见 docs/api/tasks.md。
./scripts/vllm.sh --model_name oxr restart
./scripts/vllm.sh --model_name oxr check
./scripts/start_docvlm.sh restart-
internal:应用拉起
vllm.entrypoints.openai.api_server(可选;日常联调以 external 为主)。 -
external:连接已有 OpenAI 兼容服务(
models.*.base_url)。 -
当前模型键:配置文件、
POST /api/vllm/switch-model或 Web UI 模型下拉。
cd /code/project/IDP/docvlm
uv venv .venv-docvlm
source .venv-docvlm/bin/activate
uv pip install -e .
./scripts/vllm.sh --model_name <键> restart
./scripts/start_docvlm.sh restart浏览器:http://localhost:8081/。
镜像仅含应用依赖(不含 vLLM)。构建与运行:
docker build -t docvlm:external .
docker run --rm -p 8081:8081 \
-e DOCVLM_VLLM__MODE=external \
-e DOCVLM_VLLM__CLIENT__BASE_URL=http://host.docker.internal:8000/v1 \
docvlm:external环境变量与容器连外接 vLLM 的注意点见 docs/config/env.md。
完整说明(加载顺序、CLIENT__*、按模型覆盖、Docker 示例)见 docs/config/env.md。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/version |
应用名与版本 |
| GET | /api/health |
健康与 vLLM 状态 |
| GET | /api/models |
模型列表 |
| POST | /api/vllm/switch-model |
切换当前模型键 |
| POST | /api/vllm/restart |
仅 internal:重启内置 vLLM(external 用 scripts/vllm.sh) |
internal / external 与 Base URL 仅通过配置文件 / DOCVLM_* 设定,无运行时切 mode 接口。
| POST | /task/{group}/{task} | 单图 |
| POST | /task/{group}/{task}/batch | 多图 |
config/app.yaml
docvlm/
config/settings.py
services/vllm_manager.py
models/
tasks/
api/app.py
static/