企业官网建设流程全解析

EdgeQuake文档摄取完全手册：上传、进度监控、取消重试与最常见问题排查

【免费下载链接】edgequakeEdegQuake 🌋 High-performance GraphRAG inspired from LightRag written in Rust; Transform documents into intelligent knowledge graphs for superior retrieval and generation项目地址: https://gitcode.com/gh_mirrors/ed/edgequake

🌋EdgeQuake是一款用 Rust 编写的高性能 GraphRAG 引擎，它的核心工作流就是文档摄取（Document Ingestion）：把 PDF、Markdown、TXT、JSON、图片等文件上传进来，自动完成解析、分块、实体抽取、向量化，最终沉淀为可问答的知识图谱。本文带你从上传入口讲到进度监控、取消与重试，并汇总新手最容易踩的 8 个坑，一篇读懂 EdgeQuake 文档摄取全流程。

摄取流水线：你的文档经历了什么？

上传只是开始。每个文档都要走完 6 个阶段才能被检索：

解析 Parse → 分块 Chunk → 实体抽取 Extract → 归一化 Normalize → 向量化 Embed → 存储 Store

💡 默认分块大小 1200 tokens（重叠 100 tokens），每个分块都会交给 LLM 抽取实体与关系，再写入 PostgreSQL（pgvector + Apache AGE）。

关键认知：上传成功（HTTP 202）≠ 可检索。真正耗时的是 Insert（抽取 + 嵌入）阶段，这也是为什么你必须学会监控进度。

第一步：选对上传入口（90% 的报错源于此）

EdgeQuake 提供 4 类摄取路径，不同文件类型必须走不同端点——这是新手最常踩的坑：

📌 格式矩阵：TXT/MD/JSON/图片/PDF 受支持；DOCX 和 Excel 暂不支持（SPEC-121），请导出为 PDF 或 Markdown。

快速决策树和完整字段说明见官方文档：document-upload-quick-reference.md。

WebUI 上传：三步完成

打开 Web 界面进入Documents页面，一切都很直观：

1. 拖拽或点击上传——支持 TXT、MD、JSON、PDF、PNG、JPG、GIF、WEBP（单文件上限 100MB）
2. 选择 PDF 解析器——上传框右侧的Parser for this upload下拉框可选Workspace Default、vision（扫描件/图像型 PDF，LLM 视觉 OCR）或edgeparse（数字原生 PDF，快且免费）
3. 等待状态变为 Completed——下方文档列表会实时显示每个文件的状态、实体数和摄取成本

✅经验法则：数字原生 PDF（电子报告、发票）用 edgeparse，几秒搞定；扫描件、排版复杂的学术论文用 vision（约 $0.001–0.01/页）。PDF 摄取的完整配置见 pdf-ingestion.md。

API 上传：一条 curl 搞定

# PDF 上传（推荐路径，返回 task_id） curl -X POST http://localhost:8080/api/v1/documents/pdf \ -F "file=@research_paper.pdf" \ -F "title=My Research Paper" # 纯文本上传（生产环境建议开启异步） curl -X POST http://localhost:8080/api/v1/documents \ -H "Content-Type: application/json" \ -d '{"content":"...","title":"My Doc","async_processing":true}'

🔑务必从响应中拿到task_id（形如pdf-<uuid>）——它是后续进度查询、WebSocket 订阅和取消操作的唯一钥匙。

进度监控：三种方式随时掌握状态

摄取过程可能长达几分钟，EdgeQuake 提供三种监控手段：

方式一：看 WebUI 状态徽章

上图中每行文档都有清晰的Status列。推荐看两个"展示字段"（SPEC-057 状态 SSOT）：

方式二：WebSocket 实时推送（推荐）

ws://localhost:8080/ws/progress/{task_id}

长任务（如视觉转换）建议上传后立即订阅，实时接收分块进度。

方式三：HTTP 轮询

curl http://localhost:8080/api/v1/ingestion/{task_id}/progress

各阶段典型耗时参考：

取消与重试：随时叫停，一键重来

取消正在进行的摄取

标准取消入口（所有入口共享同一套取消语义）：

curl -X POST "http://localhost:8080/api/v1/tasks/{task_id}/cancel"

三个要点：

• 取消是协作式的：正在进行的 LLM/视觉调用会在下一个检查点中止，需短暂等待
• 取消后的文档状态是cancelled而不是failed，不会污染失败统计
• PDF 场景下取消会同时终止"转换"和"摄取"两个关联任务；详细语义见 ingestion-cancel-and-fairness.md

重试失败的文档（Reprocess）

文档显示Failed，或服务重启导致 "Interrupted — use Reprocess" 时，用 reprocess 端点重试（document_id 放请求体里，不是路径）：

curl -X POST "http://localhost:8080/api/v1/documents/reprocess" \ -H "Content-Type: application/json" \ -d '{"document_id":"$DOC_ID","force":true,"mode":"full"}'

⚠️ 常见误区：写成POST /documents/{id}/reprocess是旧路由，请以请求体方式调用为准。

服务重启时，未完成的Pending任务会自动恢复被领取；若配置了EDGEQUAKE_STARTUP_AUTO_RESUME=0，被打断的Processing任务会标记为 Failed，此时统一用 Reprocess 补救。

常见问题排查清单（8 个高频坑）

更多细节见完整排障指南：common-issues.md 与 faq.md。

最佳实践与延伸阅读

• 🚀异步优先：生产环境一律async_processing: true，同步模式只适合小文本冒烟测试
• 🔑抓住 task_id：它是进度、取消、WebSocket 的唯一关联键
• 🧠复杂文档开 gleaning：max_gleaning: 2可提升 25–35% 实体召回率，代价是更多 LLM 调用
• 📊摄取完成后看指标：GET /api/v1/workspaces/{id}/metrics可查文档数、实体分布和 LLM 成本

想深入定制分块策略、自定义实体类型和 Gleaning，推荐这份深度教程：document-ingestion.md；API 契约的唯一事实来源见 openapi.snapshot.json。

掌握以上流程，你就能让任何文档库在 EdgeQuake 中平稳"着陆"，随时叫停、随时重来 🌋

【免费下载链接】edgequakeEdegQuake 🌋 High-performance GraphRAG inspired from LightRag written in Rust; Transform documents into intelligent knowledge graphs for superior retrieval and generation项目地址: https://gitcode.com/gh_mirrors/ed/edgequake