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/edgequakeEdgeQuake是一款用 Rust 编写的高性能 GraphRAG 引擎它的核心工作流就是文档摄取Document Ingestion把 PDF、Markdown、TXT、JSON、图片等文件上传进来自动完成解析、分块、实体抽取、向量化最终沉淀为可问答的知识图谱。本文带你从上传入口讲到进度监控、取消与重试并汇总新手最容易踩的 8 个坑一篇读懂 EdgeQuake 文档摄取全流程。摄取流水线你的文档经历了什么上传只是开始。每个文档都要走完 6 个阶段才能被检索解析 Parse → 分块 Chunk → 实体抽取 Extract → 归一化 Normalize → 向量化 Embed → 存储 Store 默认分块大小 1200 tokens重叠 100 tokens每个分块都会交给 LLM 抽取实体与关系再写入 PostgreSQLpgvector Apache AGE。关键认知上传成功HTTP 202≠ 可检索。真正耗时的是 Insert抽取 嵌入阶段这也是为什么你必须学会监控进度。第一步选对上传入口90% 的报错源于此EdgeQuake 提供 4 类摄取路径不同文件类型必须走不同端点——这是新手最常踩的坑我要上传…正确端点说明纯文本 / JSONPOST /api/v1/documents需Content-Type: application/json单个文件TXT/MD/JSON/图片POST /api/v1/documents/uploadmultipart 表单单个 / 多个 PDFPOST /api/v1/documents/pdf/pdf/batch⚠️ PDF 不能走/upload批量文本/图片POST /api/v1/documents/upload/batchPDF 会被拒绝服务器目录POST /api/v1/documents/scan支持递归扫描 格式矩阵TXT/MD/JSON/图片/PDF 受支持DOCX 和 Excel 暂不支持SPEC-121请导出为 PDF 或 Markdown。快速决策树和完整字段说明见官方文档document-upload-quick-reference.md。WebUI 上传三步完成打开 Web 界面进入Documents页面一切都很直观拖拽或点击上传——支持 TXT、MD、JSON、PDF、PNG、JPG、GIF、WEBP单文件上限 100MB选择 PDF 解析器——上传框右侧的Parser for this upload下拉框可选Workspace Default、vision扫描件/图像型 PDFLLM 视觉 OCR或edgeparse数字原生 PDF快且免费等待状态变为 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 fileresearch_paper.pdf \ -F titleMy 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字段含义display_status状态徽章converting→extracting→embedding→completed/failed/cancelledui_phaserunning运行中出现stopping说明正在取消界面应显示Stopping…方式二WebSocket 实时推送推荐ws://localhost:8080/ws/progress/{task_id}长任务如视觉转换建议上传后立即订阅实时接收分块进度。方式三HTTP 轮询curl http://localhost:8080/api/v1/ingestion/{task_id}/progress各阶段典型耗时参考阶段耗时解析 / 分块 / 存储毫秒级实体抽取每分块 2–10 秒主要瓶颈向量化~500ms取消与重试随时叫停一键重来取消正在进行的摄取标准取消入口所有入口共享同一套取消语义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_RESUME0被打断的Processing任务会标记为 Failed此时统一用 Reprocess 补救。常见问题排查清单8 个高频坑#症状原因与解法1Expected request with Content-Type: application/json把-F表单发到了 JSON 端点。文本用/documents-d文件用/documents/uploadPDF 用/documents/pdf2PDF 上传被拒PDF 走/upload或/upload/batch会失败必须用/documents/pdf/pdf/batch3chunk_count 0提示Low text contentPDF 是扫描件——用pdf_parser_backendvision重新上传4表格提取成一堆乱码加config{enhance_tables:true}约慢 2 倍每表 ~$0.00015双栏论文文字串行开启config{layout:{detect_columns:true}}6413 File too large单文件超过 50MB拆分 PDF 或提高上限大文件可先用max_pages试跑7文档卡在 Processing 不动查GET /api/v1/pipeline/queue-metrics本地 Ollama 默认摄取并发只有 2属正常排队8Vision 提取反复超时检查模型与 provider 是否匹配如 OpenAI 模型配了 OllamaGET /api/v1/config/effective会直接报has_mismatch更多细节见完整排障指南common-issues.md 与 faq.md。最佳实践与延伸阅读异步优先生产环境一律async_processing: true同步模式只适合小文本冒烟测试抓住 task_id它是进度、取消、WebSocket 的唯一关联键复杂文档开 gleaningmax_gleaning: 2可提升 25–35% 实体召回率代价是更多 LLM 调用摄取完成后看指标GET /api/v1/workspaces/{id}/metrics可查文档数、实体分布和 LLM 成本想深入定制分块策略、自定义实体类型和 Gleaning推荐这份深度教程document-ingestion.mdAPI 契约的唯一事实来源见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考