FAQ · 常见问题

8 问 8 答，覆盖 90% 入门疑问。

---

1 · API Key 在哪获取？

登录 console.volo.ai，进入 Settings → API Keys：

1. 点 Create New Key 创建
2. 复制密钥 — 仅展示一次，关闭即不可见
3. 保存到环境变量：export VOLO_API_KEY=volo-sk-...

安全提醒

• 不要把 API Key 提交到 Git
• 不要在浏览器前端代码中硬编码（暴露给用户）
• 怀疑泄漏立刻在控制台 Revoke
• 推荐配置 BFF（Backend-for-Frontend）转发，Key 留在你的服务端

详见 Quickstart · 安装与注册。

---

2 · 免费额度有多少？

注册即送 100 credits（积分），可消耗在：

行为	消耗
FAST 模式对话	~0.5 credit / 1k tokens
MAX 模式对话（含工具循环）	~2-5 credits / turn
Memory 上传（图片）	1 credit / MB
语义搜索	0.1 credit / 查询

[TODO: 精确计费表见控制台 Billing，本表为示例]

升级订阅获得月度额度：

• Free · 100 credits / 月
• Pro · 5000 credits / 月，含 RPM 上调
• Team · 50000 credits / 月，多用户协作
• Enterprise · 定制，含 SLA、私有部署

---

3 · 我能自部署 VOLO AI 后端吗？

可以。代码开源，技术栈：

• Java 17 + Spring Boot 3.4 + Spring AI 1.1
• PostgreSQL（向量扩展）+ R2DBC
• Redis（缓存）
• MCP 0.13.1（Model Context Protocol）

自部署适合：

• ✓ 数据合规要求严格（金融、医疗、政企）
• ✓ 已有大型 LLM 集群基础设施
• ✓ 需要深度定制 Agent 策略

不适合：

• ✗ 个人项目（运维成本高）
• ✗ 不需要修改后端逻辑（用托管版即可）

部署指南见 docs/reference/deployment.md（仓库内）。

---

4 · 支持哪些 LLM 模型？

VOLO AI 后端通过 Spring AI 适配多家：

• OpenAI · GPT-4o, GPT-4o-mini, o1, o3
• Anthropic · Claude 4.5/4.6/4.7 Sonnet/Opus
• DeepSeek · DeepSeek-V3, DeepSeek-R1
• Qwen · Qwen-Max, Qwen-Plus, Qwen-Coder
• Doubao · 字节豆包系列
• Kimi · Moonshot K1.5
• 本地模型 · 通过 Ollama / vLLM / TGI

用户可在控制台 Settings → Model Preference 设置默认模型，或在 ChatRequest 中通过 [TODO: model 字段] 临时指定。

---

5 · 如何在对话中触发 Skill？

三个触发符：

符号	用途	示例
/	Skill（如设计/代码/PM 工具）	/h-frontend-design 设计登录页
#	系统命令	#clear 清空 session / #export 导出对话
@	引用文件 / Memory	@产品需求.md 帮我做技术方案

详见 Quickstart · 第一个 Skill 和 API · Skill。

---

6 · ExecutionMode 三档怎么选？

档位	何时选	单次成本
AUTO（默认）	不知道用什么——让系统自动路由	视任务而定
FAST	简单问答、闲聊、单步操作	低（~1 credit）
MAX	复杂任务、研究、代码生成、设计、需要工具协作	高（~5-20 credits）

选错的代价：

• FAST 处理复杂任务 → 结果浅、缺乏深度
• MAX 处理简单问答 → 浪费 credits、响应慢

建议：生产环境默认 AUTO，让后端 AutoClassifier 决策；调试时手动指定。

---

7 · 如何处理 SSE 断连？

SSE 连接可能因网络抖动、代理超时（Nginx 默认 60s）、CDN 切换等断开。SDK 已封装自动重连，手动处理时：

let lastEventId: string | null = null

while (true) {
  try {
    const stream = await client.chat.stream({
      sessionId,
      userMessage,
      lastEventId, // 续传锚点
    })
    for await (const event of stream) {
      lastEventId = event.eventId
      // ... 处理事件
    }
    break // 正常结束
  } catch (err) {
    if (err instanceof VoloStreamError && retries < 3) {
      await sleep(1000 * 2 ** retries)
      retries++
      continue
    }
    throw err
  }
}

不要重发原 intent

SSE 断开后不要重新 POST /intent——会创建新 turn 并重复消耗 credits。
正确做法：调用 GET /{sessionId}/messages?since={lastTimestamp} 补齐 catch-up，或用 SDK 内建重连。

详见 Troubleshooting · SSE 断连.

---

8 · 数据安全和合规

维度	说明
存储	PostgreSQL 加密静态存储；图片/文档 COS 加密
传输	TLS 1.3 强制
隔离	多租户严格逻辑隔离（userId 强制注入所有 query）
删除权	API Key + GUI 均支持物理删除
审计	所有 Agent 工具调用留痕，按 traceInfo 可溯源
GDPR	支持数据导出 / 删除（Enterprise plan）
SOC 2	[TODO: 认证进行中]
ISO 27001	[TODO: 认证进行中]

更多：Contact · 安全报告 | volo.ai/security

---

还有问题？

• Troubleshooting — 报错排查
• Contact — 联系我们