66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
---
|
||
title: Marker 文档转换指南
|
||
lifecycle: unknown
|
||
evidence: documented
|
||
last_reviewed: 2026-09-16
|
||
last_verified: null
|
||
---
|
||
|
||
# Marker
|
||
|
||
Marker 用 GPU 将 PDF 转为 Markdown 等格式。本页依据 homelab-infra `apps/marker/README.md`、
|
||
Dockerfile 与 Kubernetes manifests，以及下列上游 API 源码整理，未查询运行环境。
|
||
源码 Deployment 仍使用 `<your-registry>/marker:latest` 占位符，不能据此认定服务已经上线。
|
||
|
||
## 使用前提与入口
|
||
|
||
先由维护者完成镜像构建、部署与可达性确认，再使用集群内入口
|
||
`http://marker.default.svc.cluster.local:8001`。所读配置没有记录外部域名或客户端认证流程。
|
||
普通应用无需重新执行 README 中的部署步骤。
|
||
|
||
镜像未固定 `marker-pdf` 版本，示例必须与实际部署的 `/docs` 接口说明核对。
|
||
上游当前 `marker_server` 默认绑定 `127.0.0.1`，而本地配置只传 `--port`；
|
||
如果所构建版本也如此，维护者需设置 `--host 0.0.0.0` 才能供 Service 访问。
|
||
这是部署前检查点，本轮未修改 manifest 或判定现场故障。
|
||
|
||
## 转换一个 PDF
|
||
|
||
在能访问该 Service 的客户端，准备一份适合测试的 `sample.pdf`，设置 `MARKER_BASE_URL`
|
||
为已确认的入口。上传会处理文件并占用 GPU，先以单个小文件串行验证：
|
||
|
||
```bash
|
||
curl --fail --silent --show-error \
|
||
-F '[email protected];type=application/pdf' \
|
||
-F 'output_format=markdown' \
|
||
"${MARKER_BASE_URL:?请设置已确认的入口}/marker/upload" \
|
||
-o marker-result.json
|
||
```
|
||
|
||
检查转换是否成功，再将 Markdown 保存到本地：
|
||
|
||
```python
|
||
import json
|
||
from pathlib import Path
|
||
|
||
result = json.loads(Path("marker-result.json").read_text())
|
||
if result.get("success") is not True:
|
||
raise SystemExit("转换失败，请检查返回的 error 字段")
|
||
Path("sample.md").write_text(result["output"])
|
||
```
|
||
|
||
接口和返回结构依据 [Marker server 源码](https://github.com/datalab-to/marker/blob/master/marker/scripts/server.py)。
|
||
HTTP 成功不等于转换成功，需要检查 `success`。返回还可能包含图片数据；仅写出 `output`
|
||
不会将图片自动保存为独立附件。需要完整图文时应按实际版本返回的图片字段另行保存并核对引用。
|
||
|
||
## 资源与文档边界
|
||
|
||
本地 README 的目标是适配 4 GB 显存，保持单副本、单 worker，并避免并发转换。
|
||
显存不足时先缩小测试文件或处理范围，不直接增加副本或并发。
|
||
Pod 没有业务 PVC，消费者应保存转换结果，不能将容器临时目录当文档库。
|
||
|
||
转换结果需要复核表格、代码、顺序及遗漏，再写入知识库；转换工具不确认文档事实或当前服务状态。
|
||
连接失败检查部署入口与监听地址，转换失败检查文件、模型加载及 GPU 资源。
|
||
依赖为 Kubernetes、GPU 设备支持、模型与临时磁盘；部署维护入口为 `apps/marker/README.md`。
|
||
|
||
来源文件的固定版本与工作区差异见[来源追溯](../sources.md#marker)。
|