千夜网

千夜网 · 公网文档 · 实施与运维

智游讲解 · 运维手册

本页聚焦“怎么部署、怎么监控、怎么控成本”，包含缓存策略、TTS 音频生成、成本监控与应急流程。

推荐部署拓扑

┌───────────────┐   ┌────────────────────┐   ┌──────────────────┐
│  zhiyou-guide │──▶│  API 网关 / Nginx   │──▶│  tour-core / AI   │
│  (H5, CDN)    │   │  (TLS/限流/日志)     │   │  explain / vision │
└───────────────┘   └────────────────────┘   └──────────────────┘
                                         │
                                         ├── Redis（缓存/限流）
                                         └── 对象存储（图片/音频）

H5 建议走 CDN；识别与讲解生成需要详细日志与成本监控，避免“看不到钱花在哪”。

讲解生成缓存策略

缓存 Key 设计

  • 基础 Key 结构：explain:{poi_id}:{exhibit_id}:{profile_hash}:{style_code}:{prompt_version}:{language}
  • POI/Exhibit ID：唯一标识点位或展品
  • Profile Hash：用户画像的哈希值，包含年龄、兴趣等
  • Style Code：讲解风格代码（如 professional、fun 等）
  • Prompt Version：提示词模板版本号
  • Language：语言代码（如 zh-CN、en-US）

TTL（生存时间）

  • 通用讲解：7 天
  • 热门 POI：30 天
  • 特殊活动：活动期间 + 7 天
  • 低频访问：3 天

命中率指标

  • 目标命中率：≥ 85%
  • 监控频率：每 5 分钟
  • 低命中率告警：< 70% 持续 10 分钟
  • 缓存预热：热门 POI 提前生成缓存

灰度策略

  • 新提示词模板：先在 10% 流量上测试
  • 缓存失效：分批次失效，避免同时重建缓存
  • 回滚机制：支持快速回滚到 previous 版本
  • A/B 测试：不同缓存策略对比效果

TTS 音频生成与缓存

音频生成

  • 音色选择：默认女声，支持多种音色
  • 语速：默认 1.0，支持 0.8-1.5 调节
  • 音频格式：MP3，比特率 128kbps
  • 生成方式：异步生成，返回任务 ID
  • 生成超时：30 秒

缓存策略

  • 缓存 Key：tts:{text_hash}:{voice_id}:{speed}
  • TTL：30 天
  • 存储方式：对象存储（OSS）
  • CDN 加速：启用 CDN 分发音频文件

移动端兼容

  • 支持的浏览器：Chrome、Safari、微信内置浏览器
  • 音频自动播放：需要用户交互后才能自动播放
  • 网络适配：支持 4G/5G 网络，自动调整音质
  • 离线播放：支持音频缓存到本地

成本监控与限额

每日预算

  • 识别 API：根据景区客流量设置
  • LLM 生成：按字数计费，设置每日上限
  • TTS 生成：按字符数计费，设置每日上限
  • 对象存储：监控存储量和流量

单 POI 生成上限

  • 每日生成次数：每个 POI 最多 1000 次
  • 相同画像+风格：24 小时内只生成一次
  • 异常检测：单个 IP 短时间内多次请求

异常报警

  • 成本超支：达到预算 80% 时预警
  • 生成失败率：> 10% 时报警
  • 识别失败率：> 20% 时报警
  • 响应时间：> 5 秒持续 5 分钟时报警

运维 Runbook：识别失败率飙升/生成超时的应急流程

识别失败率飙升

  1. 告警触发：识别失败率 > 20% 持续 5 分钟
  2. 快速定位：
    • 检查第三方识别 API 状态
    • 查看网络连接状态
    • 分析识别日志，查看失败原因分布
  3. 应急措施：
    • 切换到备用识别 provider
    • 降低识别请求频率
    • 启用本地缓存的识别结果
  4. 恢复流程：
    • 确认主 provider 恢复正常
    • 逐步切回主 provider
    • 分析失败原因，优化识别参数

生成超时

  1. 告警触发：生成时间 > 10 秒持续 5 分钟
  2. 快速定位：
    • 检查 LLM 服务状态
    • 查看队列长度
    • 分析系统资源使用情况
  3. 应急措施：
    • 启用缓存优先策略
    • 降低生成请求频率
    • 临时降级为基础讲解模板
  4. 恢复流程：
    • 确认 LLM 服务恢复正常
    • 清理队列积压
    • 分析超时原因，优化生成参数

监控与排障

  • 识别：成功率、平均耗时、top1 命中率、人工改选率。
  • 讲解：生成耗时、缓存命中率、单次成本、播放完成率。
  • 对象存储：图片/音频增长、热 key。

FAQ 入口：智游讲解 · FAQ