13. AI（向量检索 / FAQ / 文档）

条件启用：这一组接口依赖 vjmap 服务端的嵌入（embedding）模型与向量库。 若未正确配置，调用会返回 500（例如缺少 bge-large-zh-v1.5-f16.gguf 模型文件）。 在你的环境若未开启 AI 子服务，直接跳过本章。

本章覆盖 3 个接口：

---

13.0 启用探针

SDK 提供 aiEnabled() / ai_enabled()（内部调用 chatFaq）判断 AI 子服务是否可用； 失败（抛 VjmapError）则视为未启用，跳过后续调用即可。

⚠️ aiEnabled() 只探测 chatFaq 一个端点。chatFaq 可用不代表 vectorSearch/vectorDocs 可用——向量检索依赖独立子服务，aiEnabled()===true 时 vectorSearch 仍可返回 HTTP 500。调用方仍需对每个 AI 端点单独 try/catch。

if not svc.ai_enabled():
    raise SystemExit("AI 未启用，略")

---

13.1 vectorSearch — 相似性检索

按给定自然语言 query 在向量库中检索最相似的若干条文档。

请求

两种请求方式：

主要参数

POST body 还支持以下字段（VectorSearchData 结构体，GET query 不暴露）：

响应

{
  "status": "success",
  "data": [
    {
      "id": "__createPolygon",
      "content": "根据给定的点坐标数组直接绘制一个多边形",
      "metadata": { "...": "..." },
      "similarity_score": 0.8273
    },
    { "...": "..." }
  ]
}

SDK 示例

res = svc.vector_search("如何画多边形", num_documents=5)
for doc in res.get("data", []):
    print(doc["id"], doc.get("similarity_score"))

const res = await svc.vectorSearch('如何画多边形', { numDocuments: 5 });
res.data.forEach(d => console.log(d.id, d.similarity_score));

失败样例

当前测试环境缺少 embedding 模型文件，真实请求返回：

{
  "status": 500,
  "body": {
    "code": 8,
    "msg": "D:/Program Files/vjmapserver/data/ai/models/bge-large-zh-v1.5-f16.gguf is not exist"
  }
}

部署提示：部署方需根据官方文档下载 embedding 模型文件，放置于 服务端的 data/ai/models/ 目录下，并在配置中指定模型名。未配置时， vectorSearch 会失败但不影响其他子系统运行。

---

13.2 chatFaq — FAQ 知识库

请求

GET /api/v1/service/chatFaq

响应

返回一个按"主题"分组的字符串数组字典。

{
  "status": "success",
  "data": {
    "UI交互": [
      "弹出学生表单输入对话框，包括姓名、年龄(默认18)、性别",
      "获取地图的当前中心点坐标X和Y、地图级别，生成json对象，根据这数据弹出数据信息框..."
    ],
    "信息窗口": [
      "在坐标[30,50]处添加一个信息窗口，内容为\"Hello,World\""
    ],
    "几何算法": [ "..." ]
  }
}

数据源来自服务端 ./data/ai/faq/*.md，HTTP 缓存 Cache-Control: public, max-age=864000（10 天）。

SDK 示例

faq = svc.chat_faq()
for topic, items in faq["data"].items():
    print(f"- {topic}: {len(items)} 项")

const { data } = await svc.chatFaq();
for (const [topic, items] of Object.entries(data)) {
  console.log(`- ${topic}: ${items.length} 项`);
}

---

13.3 vectorDocs — 向量库文档

请求

GET /api/v1/service/vectorDocs

响应

返回一个数组，每项是知识库里的一条文档元数据：

{
  "status": "success",
  "data": [
    {
      "id": "__createPolygon",
      "content": "根据给定的点坐标数组直接绘制一个多边形",
      "metadata": {
        "category": "draw",
        "code": "...",
        "comments": "...",
        "function": "__createPolygon",
        "param": "..."
      },
      "similarity_score": 0
    }
  ]
}

similarity_score 恒为 0（此接口不做相似度计算，仅导出文档）。

SDK 示例

docs = svc.vector_docs()["data"]
print("知识库条目数：", len(docs))
print("分类统计：", {
    c: sum(1 for d in docs if d["metadata"].get("category") == c)
    for c in sorted({d["metadata"].get("category", "") for d in docs})
})

const { data: docs } = await svc.vectorDocs();
console.log('条目数：', docs.length);

---

使用建议

1. 部署前先跑探针：初始化客户端后先调 chat_faq()，失败则关闭 AI UI 入口。
2. 前端搜索：优先用 POST vectorSearch，把 searchDescription 带上业务上下文能显著提升命中率。
3. 冷启动：第一次调用 vectorSearch 会加载 embedding 模型，响应可能秒级； 第二次起基本在毫秒级。
4. 安全：vectorDocs 直接返回所有文档内容（含 code 字段），不要把它暴露给未鉴权用户。

---