Knowhere API实战教程从上传文档到获取可引用RAG检索结果的6个步骤【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhereKnowhere 是一个开源的文档解析与检索系统它的 API 能把 PDF、Word、PPT 等非结构化文档解析为带层级、带页码引用的结构化记忆让 AI Agent 和 RAG 应用直接拿到可溯源、可引用的检索证据。本教程带你走完 Knowhere API 实战的 6 个关键步骤本地部署、创建 API Key、上传文档、轮询解析任务、发起 RAG 检索、解读引用结果全程只需 curl 命令新手也能快速上手。先理解 Knowhere API 的工作方式 Knowhere 的 API 分为两代都挂在/api前缀下路由注册见 apps/api/app/api/api_router.py版本适用场景特点V1 Jobs API通用文档解析文本轨精确提取结构适合干净文档V2 Jobs APIPDF / PPTX视觉轨Vision Page由视觉模型整体理解页面两条轨道最终输出同一套 chunk 与引用 schema检索、层级、页面引用方式完全一致。核心端点一览POST /api/v1/jobs— 创建解析任务上传文档入口GET /api/v1/jobs/{job_id}— 查询任务结果GET /api/v1/documents— 浏览已解析文档POST /api/v1/retrieval/query— 发起 RAG 检索GET /api/v1/demo/catalog— 官方示例文档目录完整接口定义可参考 apps/api/app/api/v1/routes/jobs.py 和 apps/api/app/api/v1/routes/retrieval.py。步骤一一键启动本地 Knowhere API 环境 环境要求Python 3.11、uv、Docker含 compose。# 克隆仓库 git clone https://gitcode.com/gh_mirrors/know/knowhere cd knowhere # 同步依赖 uv sync --all-packages # 复制环境变量模板并填入数据库/Redis/S3/LLM 配置 cp apps/api/.env.example apps/api/.env cp apps/worker/.env.example apps/worker/.env # 启动 PostgreSQL、Redis、LocalStack 等本地基础设施 ./deploy/local-dev/start-dev.sh然后在两个终端分别启动 API 和 Workercd apps/api uv run main.py # API 服务 cd apps/worker uv run worker.py # 解析工作进程启动后 API 运行在http://localhost:5005交互式文档在http://localhost:5005/docs。启动脚本与依赖配置说明见 deploy/local-dev/start-dev.sh 和 README.md。步骤二创建 API Key2 分钟搞定本地纯 API 开发无需 Dashboard一条脚本即可创建用户和 Keycd apps/api uv run scripts/init_user.py --email youexample.com脚本 apps/api/scripts/init_user.py 会输出你的 API Key。之后所有请求都带同一个请求头export KNOWHERE_APIhttp://localhost:5005/api/v1 export API_KEY你的key步骤三上传文档创建解析任务 向 Jobs 端点发起创建请求。以 URL 方式为例也支持 S3 直传 回调模式curl -X POST $KNOWHERE_API/jobs \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d {url: https://example.com/report.pdf, namespace: demo}响应中的job_id是后续轮询的凭证。几点提示PDF 和 PPTX 建议走 V2 接口/api/v2/jobs自动使用视觉轨解析复杂版式namespace是检索隔离空间不同知识库可用不同命名空间支持格式.pdf.doc.docx.xls.xlsx.md.txt.html.jpg.png等任务创建逻辑在 apps/api/app/api/v1/routes/jobs.pyV2 版对应 apps/api/app/api/v2/routes/jobs.py。步骤四轮询任务状态等待解析完成 ⏳解析是异步的用两个端点跟踪进度# 列出所有任务可按状态过滤 curl $KNOWHERE_API/jobs?job_statuscompleted \ -H Authorization: Bearer $API_KEY # 查询单个任务结果 curl $KNOWHERE_API/jobs/$JOB_ID \ -H Authorization: Bearer $API_KEY状态变为completed后文档即进入你的文档库可以随时用 Documents API 查看curl $KNOWHERE_API/documents -H Authorization: Bearer $API_KEY curl $KNOWHERE_API/documents/$DOC_ID/chunks?chunk_typetable \ -H Authorization: Bearer $API_KEYChunks 端点支持按text/image/table/page四种类型过滤include_asset_urlstrue时还能拿到 7 天有效的图片/表格资产 URL端点定义见 apps/api/app/api/v1/routes/documents.py。偷懒技巧不想上传自己的文档Knowhere 内置了 25 份官方示例语料财报、论文、说明书GET /api/v1/demo/catalog查看目录POST /api/v1/demo/materializations一键把示例文档物化到你的命名空间直接开查。实现见 apps/api/app/api/v1/routes/demo.py。步骤五发起 RAG 检索查询 核心端点是POST /api/v1/retrieval/query最小请求体只需要querycurl -X POST $KNOWHERE_API/retrieval/query \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d { namespace: demo, query: 公司本季度的毛利率同比变化如何, top_k: 5, chunk_types: [text, table] }常用参数完整定义见 RetrievalQueryRequesttop_k返回证据数量include_document_ids/exclude_document_ids限定或排除文档chunk_types过滤text、image、table、page类型use_agentic置为false走经典 BM25 检索开启则 Agent 自主导航文档树rerank是否用 LLM 重排序步骤六解读检索结果拿到可引用证据 响应体RetrievalQueryResponse里最有价值的是这几个字段字段含义evidence组合好的证据片段文本 内联图片直接喂给下游 Agentevidence_text证据的纯文本投影表格保留 HTMLreferenced_chunks被引用的 chunk 元数据含文档、章节路径、页码decision_traceAgent 模式下的逐步决策轨迹referenced_chunks里的section_path如3. 财务分析 3.2 毛利率和page字段就是可引用性的来源——你的 RAG 应用可以据此在答案后标注来源第 12 页用户点开即可看到原始页面截图如下图所示的页面引用资产正是 Knowhere 为 Vision 轨文档生成的可溯源证据这正是 Knowhere 与传统 RAG 的区别不是返回一堆孤立片段而是返回带文档层级、页码、图表资产的可溯源证据链。内部评测显示基于 Knowhere 记忆的 Agent 首次回答准确率比裸文档高 36%反馈后准确率可达 79%6 个步骤速查清单 ✅步骤端点说明1️⃣ 启动环境start-dev.sh API/Worker本地localhost:50052️⃣ 创建 API Keyinit_user.pyBearer Token 鉴权3️⃣ 上传文档POST /api/v1/jobs拿到job_id4️⃣ 轮询任务GET /api/v1/jobs/{id}等completed5️⃣ 发起检索POST /api/v1/retrieval/query传querynamespace6️⃣ 消费证据evidencereferenced_chunks带页码章节的可引用结果 延伸阅读docs/retrieval-document-scope.md检索文档范围设计、docs/adr/README.md架构决策记录。掌握以上 6 步你就可以把任意私有文档库变成 AI Agent 的可引用外脑了。【免费下载链接】knowhereKnowhere extracts, parses, and outputs structured chunks ready for AI Agents and RAG.项目地址: https://gitcode.com/gh_mirrors/know/knowhere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
