语义搜索 API

M-Doc 提供基于向量的语义搜索接口，支持在文档中按语义相关度查找文章。

---

接口

GET /openapi/organizations/:orgSlug/documents/:docSlug/search

所需权限：read:articles

参数

路径参数

参数	类型	说明
orgSlug	string	组织标识
docSlug	string	文档标识

查询参数

参数	类型	默认值	范围	说明
q	string	—	—	搜索关键词（必填）
top_k	int	5	1-20	返回结果数量
min_score	float	0.5	0-1	最低相关度阈值

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "results": [
      {
        "article_id": 100,
        "title": "快速入门",
        "score": 0.92,
        "content": "文章内容片段...",
        "markdown_url": "https://mdoc.cc/openapi/organizations/.../content.md",
        "browser_url": "https://mdoc.cc/org/doc/articles/100"
      }
    ],
    "total": 1
  }
}

示例

# 基本搜索
curl -H "Authorization: Bearer mdoc_pat_xxxxx" \
  "https://mdoc.cc/openapi/organizations/mliev/documents/mdoc/search?q=如何配置数据库"

# 返回更多结果，降低阈值
curl -H "Authorization: Bearer mdoc_pat_xxxxx" \
  "https://mdoc.cc/openapi/organizations/mliev/documents/mdoc/search?q=认证&top_k=10&min_score=0.3"

工作原理

1. 文本分块：文章内容按 512 token 分块，50 token 重叠
2. 向量化：通过 Embedding API 将分块转换为向量
3. 存储：向量存储在 pgvector 中（HNSW 索引）
4. 搜索：查询文本转向量后，计算与所有分块的余弦相似度
5. 返回：按相似度降序返回匹配结果

向量元数据

每个向量分块存储以下元数据：

字段	说明
article_id	文章 ID
document_id	文档 ID
version_id	版本 ID
chunk_id	分块序号
title	文章标题
content	原始文本内容

前置条件

使用语义搜索需要管理员配置：

• vectorize.enabled: true
• vectorstore.enabled: true
• PostgreSQL + pgvector 扩展
• 有效的 Embedding API 密钥