使用说明

论文平台对接

给 ai-paper-backend 用：幂等建库、参考文献 upsert、上传、短索引。

鉴权：Authorization: Bearer <sv_…>。Base：LLMWIKI_BASE_URL（本地 http://localhost:8000）。
id / slug / sv_ / external_task_id 对照见 概念说明 · 常用标识。

对接方式

  • 进库：HTTP（LLMWIKI_BASE_URL + Token）
  • 写作检索：推荐百炼 Responses 挂载 MCP（模型自行 search / read）；仅当 MCP 不可达时再 HTTP 抽摘要并注入 prompt

slug：建库响应 knowledge_base.slug → 论文 form.llmwikiSlug → MCP 路径 /{slug}/mcp（或工具参数 knowledge_base）。
id：HTTP 路径用 UUID。详见 概念说明。

A. 检索成功后同步进库

流程图加载中…
步骤接口
建库POST /v1/integrations/paper/task-libraries（external_task_id=lp_task_{taskId}）
导入POST /v1/knowledge-bases/{id}/imports/references（mode=upsert）
短索引GET /v1/knowledge-bases/{id}/reference-index

form 字段：llmwikiKnowledgeBaseId、llmwikiSlug、llmwikiExternalTaskId、llmwikiReferenceCitations。
手动同步（论文侧）：POST /api/v1/learn-paper/tasks/:id/sync-llmwiki。

B. 写作时取文献

流程图加载中…
路径做法
MCP（推荐）server_url=…/{llmwikiSlug}/mcp（或全局 /mcp + 指令锁 slug）。片段经工具结果进入对话，无需业务侧预先注入大段正文。
HTTP 回退用 id 拉短索引 / 正文摘要，挑几条编号后写入写作 prompt（控 token）。

LLMWIKI_MCP_URL 须公网可达，否则走 HTTP 回退。

范围：导入多为检索摘要；OSS 个人上传不会自动进库。

推荐调用顺序（通用）

文献检索完成（~35 条）
  → POST /v1/integrations/paper/task-libraries
  → POST /v1/knowledge-bases/{id}/imports/references
  →（可选）POST .../documents/upload
  → GET  .../reference-index

重跑同一任务：同一 external_task_id + 相同 external_id/doi，不会重复插多份。

建库成功后请保存：

字段用途
knowledge_base.id导入、短索引、HTTP 摘录
knowledge_base.slugMCP /{slug}/mcp（或参数 knowledge_base）
knowledge_base.external_task_id如 lp_task_6，幂等键

1. 幂等创建任务文献库

POST /v1/integrations/paper/task-libraries
Authorization: Bearer <token>
Content-Type: application/json

{
  "external_task_id": "lp_task_abc123",
  "name": "论文任务-大模型评测",
  "description": "可选"
}
字段说明
external_task_id论文平台任务 ID，同一用户下唯一；已存在则返回原库
name显示名；冲突时自动加后缀
description可选

响应

{
  "created": true,
  "knowledge_base": {
    "id": "...",
    "name": "论文任务-大模型评测",
    "slug": "admin-uid2-6",
    "kind": "task_literature",
    "external_task_id": "lp_task_abc123",
    "source_count": 0,
    "wiki_page_count": 0
  }
}

请持久化 id 与 slug（slug = MCP 唯一空间键）。created: false 表示复用已有库。

2. 批量导入参考文献（防重复）

POST /v1/knowledge-bases/{kb_id}/imports/references
Authorization: Bearer <token>
Content-Type: application/json

{
  "mode": "upsert",
  "references": [
    {
      "external_id": "ref_1",
      "title": "示例论文",
      "authors": ["张三", "李四"],
      "journal": "某学报",
      "year": "2024",
      "doi": "10.1000/xyz",
      "abstract": "……",
      "keywords": ["A", "B"]
    }
  ]
}

去重规则（按优先级）

  1. external_id（推荐传论文侧稳定 id）
  2. 规范化后的 doi
  3. 若都没有：自动生成 doi:… 或 title:… 作为 external_id
mode行为
upsert（默认）命中则更新正文/元数据并重建切块
skip_existing命中则跳过

响应

{
  "created": 30,
  "updated": 5,
  "skipped": 0,
  "results": [
    { "action": "created", "document_id": "...", "external_id": "ref_1", "title": "…" }
  ]
}

每条会写成 Markdown 笔记（可检索），标签含 paper-import。

3. 简易文件上传（multipart）

无需 TUS，Nest 直接 FormData：

POST /v1/knowledge-bases/{kb_id}/documents/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file=<binary>
filename=paper.pdf          # 可选，默认用上传文件名
external_id=ref_1           # 可选；同键则覆盖并重新解析
path=/                      # 可选

成功 201，文档 status 先为 pending，解析完成后为 ready。
单文件上限 100MB；类型与 TUS 相同。

仍保留 TUS 上传 用于可断点续传。

4. 参考文献短索引

GET /v1/knowledge-bases/{kb_id}/reference-index
Authorization: Bearer <token>

返回参考文献短列表（编号、标题等），供引用表或 HTTP 回退时挑条注入写作 prompt。主路径写作仍应走 MCP 工具检索，不必将整表正文放入提示词。

{
  "knowledge_base_id": "...",
  "count": 35,
  "items": [
    {
      "index": 1,
      "document_id": "...",
      "title": "…",
      "citation": "[1] 标题。作者。期刊，2024。 DOI: …",
      "external_id": "ref_1",
      "doi": "10.1000/xyz",
      "status": "ready"
    }
  ]
}

与论文 retrievedReferences 的映射建议

论文字段导入字段
稳定 id / 数组下标external_id（强烈建议）
titletitle
authorInfo[].nameauthors
journalInfo.namejournal
year / journalInfo.yearyear
doidoi
abstrabstract
整条原始对象raw（可选透传）

相关