千夜网

千夜网 · 公网文档 · 集成与对接

智游讲解 · API 对接

本页给出智游讲解（文旅域）的接口分组与对接约定（先骨架，后续与实际 OpenAPI 同步）。

接口分组（建议前缀）

Tour Core
/api/v1/tour/*
景区/POI/展品、收藏、参观记录、任务与奖励。
Vision Recognition
/api/v1/vision/recognize
拍照识别 → 候选列表（topN），返回置信度与候选实体类型。
AI Explain
/api/v1/explain/*
风格库、画像推荐、讲解生成、TTS 任务。

识别接口约定（MVP）

MVP 先接第三方识别。服务端需记录 provider 与耗时，并支持把“最终确认的 POI/展品”回写到识别日志，便于纠错回流。 

POST /api/v1/vision/recognize
Content-Type: multipart/form-data

file: <image>

Response:
{
  "candidates": [
    { "kind": "POI", "id": 101, "name": "…", "confidence": 0.86 },
    { "kind": "EXHIBIT", "id": 9001, "name": "…", "confidence": 0.74 }
  ],
  "provider": "third-party-x",
  "elapsed_ms": 421
}

识别链路：第三方识别 provider 适配标准

输入

  • 支持图片格式：JPG、PNG、WebP
  • 支持图片大小：最大 10MB
  • 支持图片分辨率：建议不超过 4096x4096
  • 支持上传方式：multipart/form-data

输出

  • 返回格式：JSON
  • 候选列表：最多返回 5 个候选结果
  • 每个候选包含：kind（POI/EXHIBIT）、id、name、confidence
  • 额外信息：provider 名称、处理耗时（elapsed_ms）

候选排序

  • 按 confidence 降序排列
  • confidence 范围：0-1，越高越可信
  • 当 confidence < 0.5 时，视为低置信度结果

置信度阈值

  • 高置信度：confidence ≥ 0.8，可考虑自动确认
  • 中等置信度：0.5 ≤ confidence < 0.8，需要用户确认
  • 低置信度：confidence < 0.5，建议提示用户手动选择

失败兜底

  • 网络错误：重试 3 次，每次间隔 1 秒
  • 识别失败：返回空候选列表，引导用户手动搜索
  • 超时处理：设置 10 秒超时，超时后返回失败
  • 异常日志：记录详细错误信息，便于排查

Provider 适配流程

  1. 在服务端配置 provider 信息（API key、endpoint 等）
  2. 实现 provider 适配器，统一输入输出格式
  3. 部署灰度测试，对比不同 provider 的效果
  4. 监控识别成功率、平均耗时、成本
  5. 根据效果动态调整 provider 优先级

鉴权与账号边界（重要）

游客端账号体系为独立域（SaaS 给三方运营公司使用），不复用体育域 qx_users。

总后台（RuoYi）账号仅用于运营/景区管理员；RuoYi 与业务域对接采用内网 token，不直接跨库读写。