Memorix REST API

面向程序化集成的完整 REST API：配置 Embedding / OCR / Chat 模型，管理知识库与文档，触发索引，执行混合检索与 RAG 问答，并查看可观测日志与评测指标。

下文路径均带 /v1 前缀；与 design/api.md 及线上 OpenAPI 规范一致。

基础信息

认证

所有业务接口在请求头携带 Bearer Token：

Authorization: Bearer <token>

创建 API Key 需先用 JWT 登录；之后数据面可全程使用 mmx_ 密钥。 控制台 API 密钥

统一响应

成功时 data 承载业务载荷；分页列表额外包含 meta。

{
  "success": true,
  "message": "ok",
  "data": { }
}

分页示例：

{
  "success": true,
  "message": "ok",
  "data": [ ],
  "meta": {
    "total": 120,
    "page": 1,
    "page_size": 20,
    "has_more": true
  }
}

错误时 HTTP 4xx/5xx，body 为 { detail: "…" }。未配置 Embedding 时索引返回 detail=EMBEDDING_NOT_CONFIGURED。

端到端最小流程

以下 curl 均使用 API Key，按顺序执行即可跑通检索/问答。

BASE="https://<your-host>/v1"
AUTH="Authorization: Bearer mmx_live_xxx"
JSON="Content-Type: application/json"

1. 1. 配置 Embedding（必须）

   curl -X PUT "$BASE/embedding-config" -H "$AUTH" -H "$JSON" -d '{
     "model_name": "text-embedding-v3",
     "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "api_key": "sk-dashscope-xxx",
     "dimensions": 1536
   }'

2. 2. 配置 OCR 与 Chat（可选）

   curl -X PUT "$BASE/ocr-config" -H "$AUTH" -H "$JSON" -d '{
     "model_name": "qwen-vl-ocr-latest",
     "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "api_key": "sk-dashscope-xxx",
     "enabled": true
   }'
   
   curl -X POST "$BASE/llm-providers" -H "$AUTH" -H "$JSON" -d '{
     "name": "deepseek-chat",
     "provider_type": "openai",
     "api_url": "https://api.deepseek.com/v1",
     "api_key": "sk-deepseek-xxx",
     "model_name": "deepseek-chat"
   }'

3. 3. 创建知识库

   curl -X POST "$BASE/collections" -H "$AUTH" -H "$JSON" -d '{
     "name": "handbook"
   }'

4. 4. 上传并索引文档

   # 创建文档记录
   curl -X POST "$BASE/documents" -H "$AUTH" -H "$JSON" -d '{
     "collection_id": "COLLECTION_ID",
     "source_type": "pdf",
     "filename": "handbook.pdf"
   }'
   
   # 上传文件（multipart，字段名 file）
   curl -X POST "$BASE/documents/DOCUMENT_ID/upload" -H "$AUTH" \
     -F "file=@./handbook.pdf"
   
   # 标记上传完成
   curl -X POST "$BASE/documents/DOCUMENT_ID/complete-upload" -H "$AUTH"
   
   # 触发索引
   curl -X POST "$BASE/documents/DOCUMENT_ID/reindex" -H "$AUTH"

5. 5. 轮询索引状态

   status 为 ready 即可检索；也可 GET /v1/index-jobs/{job_id}

   curl "$BASE/documents/DOCUMENT_ID/index-status" -H "$AUTH"

6. 6. 检索 / 问答

   # 检索
   curl -X POST "$BASE/retrieve" -H "$AUTH" -H "$JSON" -d '{
     "collection_id": "COLLECTION_ID",
     "query": "如何重置密码？",
     "top_k": 5
   }'
   
   # RAG 问答
   curl -X POST "$BASE/chat" -H "$AUTH" -H "$JSON" -d '{
     "collection_id": "COLLECTION_ID",
     "query": "如何重置密码？"
   }'

API Key

创建响应中的 token 仅返回一次，请妥善保存。

POST /v1/api-keys
Authorization: Bearer <supabase-jwt>

{
  "name": "server-integration",
  "scopes": [
    "collections:write",
    "documents:write",
    "retrieve:invoke",
    "chat:invoke"
  ],
  "expires_at": null,
  "test": false
}

Embedding 配置

每租户一份；向量维度须为 1536。更换模型后需对文档 reindex。

OCR 配置

仅对 PDF 无文本层的图片页触发；与 Embedding 凭证独立。

Chat 模型（LLM Providers）

知识库（Collections）

文档（Documents）

解析支持：pdf、txt、md。

上传与索引

上传与索引解耦：upload 保存文件，complete-upload 标记完成，reindex 才建立向量索引。

IndexJob 示例：

{
  "id": "uuid",
  "document_id": "uuid",
  "job_type": "reindex",
  "status": "running",
  "stage": "embed",
  "progress": 55
}

检索（Retrieve）

混合检索（向量 + 全文 + 查询扩写），不生成回答。可选头 X-Memorix-Request-Source。

{
  "query": "如何重置密码？",
  "collection_id": "uuid",
  "contexts": [
    {
      "chunk_id": "uuid",
      "content": "切片正文…",
      "score": 0.82,
      "vec_score": 0.79,
      "fts_score": 0.41,
      "citation": {
        "document_id": "uuid",
        "filename": "handbook.pdf",
        "page": 12,
        "heading_path": ["账户", "安全"],
        "chunk_index": 34
      }
    }
  ],
  "meta": {
    "strategy": "hybrid",
    "latency_ms": 130
  }
}

问答（Chat）

检索 + 生成；需已配置 Chat 模型。响应含 contexts、citation 与可选 evaluation 评分。

检索评估

可观测

工作区与账户

附录

文档状态

uploaded → parsing → splitting → indexing → ready | failed

索引阶段

parse(10) → split(35) → embed(55) → index_write(80) → done(100)

API Key Scopes

collections:read · collections:write · documents:read · documents:write · retrieve:invoke · chat:invoke

常见问题

• EMBEDDING_NOT_CONFIGURED：先 PUT /v1/embedding-config
• 问答无模型：POST /v1/llm-providers 或在 body 传 llm_provider_id
• PDF 图片页无内容：配置 OCR 后 reindex
• 更换 Embedding 后检索为空：对旧文档 POST reindex