Skip to content

api-reference.md

Latest commit

 

History

History
257 lines (186 loc) · 12.4 KB

api-reference.md

File metadata and controls

257 lines (186 loc) · 12.4 KB
Raw

LLM-Wiki API 业务语义文档

版本: V1
Base URL: http://localhost:8000/api
Swagger UI: http://localhost:8000/docs（自动生成）
最后更新: 2026-05-03

一、概述

本文档描述 LLM-Wiki 系统所有 API 端点的业务语义——即每个接口在知识库工作流中的作用、适用场景和调用时机，而非技术参数细节。技术参数请查阅 Swagger UI。

认证说明

  • 大部分写操作（创建、修改、删除）需要认证，携带 Authorization: Bearer <token> 头
  • 读操作（浏览、搜索）通常无需认证
  • 角色体系：general（普通用户） < core（核心成员） < maintainer（维护者） < admin（管理员）

二、认证模块 (/api/auth)

这些接口负责用户的身份认证与会话管理。

接口 方法 认证 业务说明
/auth/register POST 无需 用户注册。创建新账户。密码要求 8 位以上且包含字母和数字。用户名 3-50 位，仅允许字母、数字、下划线和中文。注册成功后自动登录
/auth/login POST 无需 用户登录。验证用户名密码，返回 JWT Token。同一 IP 每分钟最多 5 次尝试，超限返回 429
/auth/logout POST 无需 登出。前端清除本地存储的 Token 即可，后端无状态
/auth/me GET 需登录 获取当前用户信息。返回已登录用户的详细资料（角色、邮箱等）

典型场景：管理员通过 /auth/register 创建团队账号 → 成员通过 /auth/login 登录 → 前端存储 Token → 后续请求携带 Token

三、知识库浏览 (/api/pages)

这些接口用于浏览、检索和编辑 Wiki 知识库中的所有页面。

接口 方法 认证 业务说明
/pages GET 无需 页面列表。支持按类型过滤（paper/entity/concept/synthesis），分页浏览。这是知识库浏览的主入口
/pages/{id} GET 无需 页面详情。返回页面的完整 Markdown 内容和 Frontmatter 元数据。前端据此渲染阅读视图
/pages/{id} PUT 需登录 编辑页面。手动修改页面内容（Markdown 源码）。适用于人工修正 LLM 生成的内容、补全信息
/pages/{id}/manual-review POST 需登录 人工审核。对 LLM 生成的页面进行人工判定：批准（approve）、驳回（reject）、要求修改（request_changes）
/pages/{id}/recheck POST 需登录 复审请求。对已通过审核的页面触发重新审核（如发现了新问题或原文有更新）
/pages/{id}/history GET 无需 版本历史。查看页面的所有历史版本列表（基于 Git 自动备份）
/pages/{id}/history/{version} GET 无需 历史版本详情。查看某个历史版本的完整内容，支持版本对比
/pages/rescan POST 无需 重新扫描索引。当文件系统有变更（新生成的文件）但未反映在前端时，手动触发 Vault 重新扫描

典型场景：

用户浏览知识库 → /pages (列表) → 点击某论文 → /pages/{id} (详情)
发现内容有误 → 点击编辑 → /pages/{id} PUT (保存修改)
                  → 或 /pages/{id}/manual-review POST (驳回让 LLM 重生成)

四、原文管理 (/api/raw)

"原文"指的是 PDF 转换后的原始 Markdown 文件，是 Wiki 页面的数据源头。

接口 方法 认证 业务说明
/raw GET 无需 原文列表。列出所有可用的原始 Markdown 文档，支持搜索和分页
/raw/{id} GET 无需 原文详情。获取原始 Markdown 的完整内容。用于阅读、审核比对
/raw/{id} PUT 需登录 编辑原文。手动修改原始 Markdown 内容或文件名。适用于修正 PDF 转换错误（如标题识别错误、段落断裂）
/raw/{id}/pdf GET 无需 获取对应PDF文件。返回与原文关联的原始 PDF 文件（用于分屏对比审核）

典型场景：

审核 Wiki 页面质量 → 打开原文对比 → /raw/{id} (查看原文)
                     → /raw/{id}/pdf (左侧原文, 右侧PDF 分屏审核)
发现转换错误 → 编辑 → /raw/{id} PUT (手动修正)
              → 重新触发导入 → Agent_G 用修正后的原文重新生成

五、PDF 管理 (/api/pdf)

完整的 PDF 生命周期管理：上传 → 存储 → 转换 → 清理。

接口 方法 认证 业务说明
/pdf/upload POST 需登录 上传 PDF。将 PDF 文件上传到服务器存储。返回文件信息
/pdf/list GET 无需 PDF 列表。查看所有已上传的 PDF 及其状态（pending/转换中/已完成/失败）
/pdf/convert POST 需登录 PDF 转 Markdown。调用 Marker 引擎将 PDF 转为 Raw Markdown，存入 Obsidian Vault。耗时 30-120 秒，同步等待
/pdf/{filename} DELETE 需登录 删除 PDF。同时删除物理文件和数据库记录，关联的 Markdown 也会被删除

典型场景：

用户找到一篇新论文 → /pdf/upload (上传PDF)
                  → /pdf/convert (转为Markdown)
                  → 转换完成后 → /api/pages (刷新页面列表)
                  → 选择新论文 → 查看或编辑 Markdown

六、搜索与问答 (/api/search, /api/query)

知识库的核心交互方式：搜索和自然语言问答。

接口 方法 认证 业务说明
/search GET 无需 知识库搜索。混合搜索（向量语义 + 关键词匹配），返回匹配的 Wiki 页面列表。支持按类型过滤
/query POST 无需 自然语言问答 (RAG)。用户用自然语言提问 → 系统从知识库检索相关上下文 → LLM 基于上下文生成回答。返回答案、来源引用和推荐追问
/hot-queries GET 无需 热门查询。返回系统中的历史热门搜索词，用于引导新用户
/recent-updates GET 无需 最近更新。返回最近修改的页面列表，让用户了解知识库最新变化

搜索 vs 问答的区别：

  • 搜索（/search）：返回匹配的页面列表，用户自己阅读
  • 问答（/query）：LLM 直接给出答案，附带来源引用

七、系统健康 (/api/health-check, /api/status)

系统运行状态监控和知识库质量体检。

接口 方法 认证 业务说明
/status GET 无需 系统状态。返回知识库概况：总页面数、各类型分布、审核通过率、平均评分
/health-check POST 无需 健康体检。运行完整的知识库质量检查。支持分层运行：layer1（快速规则检查）、layer2（LLM 深度检查）、all（全部）。返回详细的健康报告，包含问题列表、统计数据和修复建议

健康体检报告包含：

  • 孤儿页面（存在于文件系统但无任何页面引用）
  • 断裂的 Wiki 链接（引用了不存在的页面）
  • Frontmatter 缺失或不完整
  • 论文结构不完整（缺少必填章节）
  • 重复实体检测
  • Layer 2: 缺少概念页面建议、低质量页面抽样

典型场景：

定期维护 → /health-check (全面体检)
         → 查看报告中的问题列表
         → 对可自动修复的问题点击"修复"
         → 对需人工处理的记入改进计划

八、自动修复 (/api/fix)

将健康体检发现的问题自动修复，减少人工干预。

接口 方法 认证 业务说明
/fix/frontmatter/{id} POST admin/maintainer 修复 Frontmatter。自动从页面内容中提取标题等信息，补全缺失的 Frontmatter 字段
/fix/regenerate-paper/{id} POST admin/maintainer 删除并重新生成论文。删除一篇不完整论文及其关联的实体/概念页面，从源文件重新生成。异步任务：立即返回 task_id，通过轮询获取结果
/fix/task-status/{task_id} GET 无需 查询异步任务状态。检查 re-generate 等异步任务的进度（pending/running/completed/failed）
/fix/broken-link/{id} POST admin/maintainer 修复断裂链接。对页面中的无效 Wiki 链接执行移除或替换操作
/fix/merge-entities POST admin/maintainer 合并重复实体。手动指定两个重复实体，将其合并为一个（保留其中一个，更新所有引用）

九、批量导入 (/api/ingest)

一次性导入多篇论文的编排管理。

接口 方法 认证 业务说明
/ingest/pending GET 需登录 待处理文档列表。显示 Raw 目录中尚未处理的文档数量
/ingest/run POST 需登录 执行批量导入。启动 Phase 4 流水线，处理指定数量的待处理文档。可指定 limit（处理几个）、retry_failed（重试失败文档）
/ingest/log GET 需登录 导入日志。查看最近一次批量导入的详细日志输出

典型场景：

一次性上传 10 篇 PDF → 全部转换为 Markdown
                   → /ingest/pending (确认待处理)
                   → /ingest/run?limit=10 (批量处理)
                   → 等待完成 → /api/pages (检查新生成的页面)

十、知识图谱 (/api/graph)

可视化展示知识库中页面之间的引用关系。

接口 方法 认证 业务说明
/graph/data GET 无需 全局图谱数据。返回所有页面之间的引用关系（节点+边），用于渲染知识图谱总览
/graph/neighbors/{node_id} GET 无需 邻居子图。查询某个页面（节点）指定深度内的关联页面
/graph/stats GET 无需 图谱统计。返回节点数、边数、聚类系数等图谱结构指标

十一、资产管理 (/api/assets)

接口 方法 认证 业务说明
/assets GET 无需 静态资源列表。返回 PDF 等文件资源的访问路径

十二、用户管理 (/api/users)

管理员专用的用户管理功能。

接口 方法 认证 业务说明
/users GET admin 用户列表。查看系统中所有注册用户
/users/{id} GET admin 用户详情
/users/{id}/role PUT admin 修改角色。变更用户的权限级别
/users/{id}/status PUT admin 启用/禁用用户。控制用户是否可以登录
/users/{id}/reset-password POST admin 重置密码。为用户生成随机新密码

十三、系统配置 (/api/config)

接口 方法 认证 业务说明
/config GET admin 读取配置。查看当前的系统配置（LLM 参数、路径、评分权重等）
/config PUT admin 更新配置。修改系统配置并即时生效

十四、系统维护

接口 方法 认证 业务说明
/refresh POST admin 刷新系统。触发 Vault 重新扫描和其他缓存刷新
/ GET 无需 根端点。API 版本信息和健康状态确认

附录：接口使用速查

按用户角色推荐

角色 常用接口
普通读者 /pages, /pages/{id}, /search, /query
内容编辑者 (core) 以上 + /pages/{id} PUT, /raw/{id} PUT
系统维护者 (maintainer) 以上 + /fix/*, /ingest/*
管理员 (admin) 以上全部 + /users/*, /config

按工作流推荐

工作流 涉及接口
导入新论文 /pdf/upload → /pdf/convert → /ingest/run → /pages
阅读知识 /pages → /pages/{id}
搜索问答 /search 或 /query
内容审核 /pages/{id} → /raw/{id} → /pages/{id}/manual-review
系统维护 /health-check → /fix/* → /status
用户管理 /users 系列

Swagger UI 提供完整的技术参数（请求体结构、响应模型、类型定义），访问 http://localhost:8000/docs 查看。