开发者 · API 与集成

用 REST API跑通完整 RAG

Memorix 提供 OpenAI 风格信封的 REST API：JWT 仅在控制台创建 API Key 时需要一次，之后纯前端或后端服务均可只用 mmx_live_ Key 完成配置、上传、索引、混合检索与带引用问答。

路径前缀 /v1 · 与 design/api.md 及线上 Swagger 一致 · 支持多模态 attachments 与诊断 meta

完整 API 文档注册获取 API Key

三种常见集成方式

按你的应用架构选择：密钥永远留在服务端，浏览器只调你自己的 BFF 或 Memorix（若已配置 CORS）。

纯前端 + BFF

白板、无代码工具在自有后端保存 mmx_live_ Key，前端只请求你的 API；由 BFF 代理 Memorix 的 collections / documents / chat。

服务端直连

Node、Python、Go 等服务用 API Key 调用全部数据面接口；适合客服机器人、企业内训、批处理索引流水线。

控制台先行

先在控制台配置 Embedding / Chat、上传试文档、用 Playground 验证召回，再复制 curl 示例到代码里，降低联调成本。

认证与 API Key

业务接口统一使用 Authorization: Bearer <token>。API Key（mmx_live_ / mmx_test_）绑定租户，适合生产集成；Supabase JWT 用于控制台与管理类接口。

阅读认证章节

创建 API Key 需 JWT 登录控制台，token 仅创建时返回一次，请立即保存

API Key 可声明 scopes（collections、documents、retrieve、chat 等），最小权限原则

使用 API Key 时多数接口可省略 tenant_id，默认限定在该 Key 所属租户

索引前必须 PUT /v1/embedding-config，否则 reindex 返回 EMBEDDING_NOT_CONFIGURED

端到端快速开始

五步从密钥到可引用问答；下列 curl 可直接替换 BASE 与 Bearer 后执行。

BASE=https://<your-host>/v1

1获取 API Key

仅本步需要控制台 JWT；之后全部使用 mmx_live_ Key。

# 控制台登录后创建 API Key（仅此步需 JWT）
curl -X POST "$BASE/api-keys" \
  -H "Authorization: Bearer <supabase_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "server-integration",
    "scopes": ["collections:write", "documents:write", "retrieve:invoke", "chat:invoke"]
  }'
# 响应 data.token 仅返回一次，请保存 mmx_live_...

2配置模型（BYOK）

Embedding 必填；OCR / Chat / Rerank / 多模态可选，各自独立 api_key 与 model_name。

curl -X PUT "$BASE/embedding-config" \
  -H "Authorization: Bearer mmx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "text-embedding-v3",
    "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "sk-xxx",
    "dimensions": 1536,
    "query_rewrite_model": "qwen-plus"
  }'

# 可选：OCR / Chat / Rerank / 多模态（各自独立 Key）
curl -X PUT "$BASE/ocr-config" -H "Authorization: Bearer mmx_live_xxx" ...
curl -X POST "$BASE/llm-providers" -H "Authorization: Bearer mmx_live_xxx" ...
curl -X PUT "$BASE/rerank-config" -H "Authorization: Bearer mmx_live_xxx" ...
curl -X PUT "$BASE/multimodal-config" -H "Authorization: Bearer mmx_live_xxx" ...

3创建知识库

POST /v1/collections 返回 collection_id，后续文档与检索均挂在此库下。

curl -X POST "$BASE/collections" \
  -H "Authorization: Bearer mmx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-docs"}'
# -> data.id 即 COLLECTION_ID

4上传并索引

创建文档 → multipart 上传 file → complete-upload → reindex → 轮询 index-status 至 ready。

curl -X POST "$BASE/documents" -H "Authorization: Bearer mmx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"collection_id": "COL_ID", "filename": "report.pdf", "source_type": "pdf"}'

curl -X POST "$BASE/documents/DOC_ID/upload" \
  -H "Authorization: Bearer mmx_live_xxx" -F "file=@report.pdf"

curl -X POST "$BASE/documents/DOC_ID/complete-upload" \
  -H "Authorization: Bearer mmx_live_xxx"

curl -X POST "$BASE/documents/DOC_ID/reindex" \
  -H "Authorization: Bearer mmx_live_xxx"

curl "$BASE/documents/DOC_ID/index-status" \
  -H "Authorization: Bearer mmx_live_xxx"

5检索与问答

retrieve 返回切片与引用；chat 需已配置 LLM Provider，响应含 meta 与 RAG 评分。

curl -X POST "$BASE/retrieve" \
  -H "Authorization: Bearer mmx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "COL_ID",
    "query": "合同中的违约责任条款？",
    "top_k": 5
  }'

curl -X POST "$BASE/chat" \
  -H "Authorization: Bearer mmx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "COL_ID",
    "query": "总结三份合同的风险点",
    "attachments": [{"type": "image", "url": "https://..."}]
  }'

BYOK：按接口分轨配置

不同能力使用不同供应商密钥，互不影响；平台不代扣模型费用。

模型配置 API 参考

PUT /v1/embedding-config：向量模型 + 可选 query_rewrite_model（须为对话模型，非 embedding 名）

PUT /v1/ocr-config：扫描页 / 图片页 OCR

POST /v1/llm-providers：/v1/chat 生成答案

PUT /v1/rerank-config：复杂问句交叉编码器重排

PUT /v1/multimodal-config：Content List 解析、VLM 增强、知识图谱、附图查询

核心端点速览

完整列表与请求体字段见 /docs；下表为最常调用的路径。

数据面 · 主流程

Method	Path	说明	鉴权
PUT	/v1/embedding-config	租户 Embedding 配置（索引与检索向量化）	API Key
POST	/v1/collections	创建 / 列出知识库	API Key
POST	/v1/documents	创建文档记录	API Key
POST	/v1/documents/{id}/reindex	触发解析、多模态增强、切分与向量索引	API Key
POST	/v1/retrieve	混合检索 + 扩写 + 可选 Rerank / 图谱加分	API Key
POST	/v1/chat	检索后流式或非流式生成，带引用与评测分	API Key

配置面 · BYOK

Method	Path	说明	鉴权
PUT	/v1/ocr-config	PDF 图片页 OCR（独立 Key）	API Key
PUT	/v1/rerank-config	租户 Rerank API 配置	API Key
PUT	/v1/multimodal-config	多模态解析、图谱、附图查询开关	API Key
POST	/v1/llm-providers	注册 Chat 模型 Provider	API Key

交互式 OpenAPI 与更多端点（评测集、检索日志、Webhook）见 /docs

进阶：诊断 meta 与多模态

retrieve / chat 响应中的 meta 包含策略、扩写变体、向量/全文命中数、Rerank 来源、graph_hints、multimodal_query 等，便于在 Playground 外自建调试面板。请求体可传 attachments 数组做附图提问。

# 检索 / 对话响应 meta 示例字段
{
  "strategy": "hybrid",
  "rewrite_variants": ["...", "..."],
  "vector_hits": 12,
  "fts_hits": 4,
  "rerank_source": "tenant",
  "graph_hints": [{"entity": "违约责任", "chunk_ids": ["..."]}],
  "multimodal_query": true,
  "rag_scores": { "context_recall": 0.82, "faithfulness": 0.91 }
}

检索与 Chat 字段说明