常见问题 FAQ

完成合同签署后，AiWma 商务团队会通过邮件发送初始 API Key（生产环境）。 你也可以在 Dashboard 的"设置 → API 密钥"页面自助生成开发环境 Key（前缀为 aiwma_dev_）。

Key 格式：aiwma_{env}_{clientCode}_{32位随机字符}，例如 aiwma_dev_XM001_a1b2c3d4…。 平台只保存哈希值，Key 明文仅在生成时展示一次，请立即妥善保存。

立即登录 Dashboard → "设置 → API 密钥" → 点击对应 Key 的"吊销"按钮。 吊销后该 Key 将在 60 秒内在所有节点失效。

然后生成新 Key 并更新到你的服务器环境变量中。如果有任何疑似滥用迹象， 请同时联系 AiWma 支持团队开展用量审计。

• 开发环境（aiwma_dev_）：月免费额度 500 次会话 / 20 次采访，响应不计入生产配额，日志保留 7 天，不触发计费告警。
• 生产环境（aiwma_prod_）：按合同配额计费，SLA 保证，日志保留期按 compliance.dataRetention 配置。

两种 Key 路由至相同的 API Endpoint（api.aiwma.com），通过 Key 前缀自动区分环境。

可以。每个 clientCode 可以创建最多 10 个并发有效的 Key（开发和生产合计）。 建议为每个部署环境（开发、测试、预发布、生产）分别使用独立的 Key， 便于追踪用量来源和快速吊销。

按以下顺序检查：

1. 打开浏览器 DevTools → Network 标签页，确认 widget.aiwma.com/v1/widget.js 已成功加载（状态码 200）。
2. 查看 Console 是否有报错，常见报错：
   • Invalid clientCode：检查 window.AiWmaConfig.clientCode 是否正确。
   • API Key not authorized：确认使用的是 aiwma_prod_ 前缀的生产 Key，且该 Key 未被吊销。
3. 检查页面的 CSP（Content-Security-Policy）响应头是否允许加载来自 *.aiwma.com 的脚本和 iframe。
4. 确认 window.AiWmaConfig 定义在 <script src="…widget.js"> 之前。

推荐在根组件（如 _app.tsx 或 App.vue）的 useEffect / mounted 生命周期中动态注入脚本：

useEffect(() => {
  window.AiWmaConfig = {
    clientCode: "XM001",
    apiKey: process.env.NEXT_PUBLIC_AIWMA_KEY,
  };
  const s = document.createElement("script");
  s.src = "https://widget.aiwma.com/v1/widget.js";
  s.async = true;
  document.head.appendChild(s);
}, []);

这样可以确保脚本在客户端渲染后才加载，避免 SSR 环境下 window 未定义的错误。 详细说明见 网页组件集成。

影响响应时间的主要因素（从最常见到最少见）：

1. VAD 静音检测：默认 minSilenceMs: 600，用户停顿不够久，引擎还在等待。可以在配置中降低至 400 ms，但会增加截断风险。
2. 网络延迟：客户端到边缘节点的 RTT。国内用户建议启用 CDN 加速（联系商务开通）。
3. LLM 云端延迟：高峰期云端模型响应变慢。可在配置中启用 promptCaching.enabled: true 减少重复令牌消耗。
4. 知识库检索超时：RAG 向量搜索超过 1s。检查向量数据库集合大小和索引状态。

P50 基准延迟（语音全链路）：约 380 ms；P95：约 980 ms。超出 P95 建议联系支持排查。

AiWma 有三类自动转人工触发条件，可在 client.yaml 中配置：

• 意图触发：用户说出了 triggerIntents 中的意图（如"转人工""我要投诉"）。
• 置信度低：AI 对当前意图的置信分连续 2 轮低于阈值（0.45）。
• 会话异常：会话状态进入 error（如模型超时连续 3 次）。

触发后，平台通过 handover.handoverTarget 发送 Webhook，你的系统接管后可调用 window.AiWma.close() 关闭挂件。 详见 网页组件集成 中的事件回调章节。

默认行为：挂件使用 sessionStorage 存储当前 Session ID，刷新页面后 Session 重置，对话历史不会自动显示。

如需恢复历史，可以在初始化时传入用户标识：

window.AiWmaConfig = {
  clientCode: "XM001",
  apiKey: "...",
  userId: "user_abc123",        // 传入你的用户 ID
  sessionPersistence: "24h",    // 会话历史保留 24 小时
};

平台会为同一 userId 在有效期内恢复最近一次未完成的会话记录。

采访进入 ENDED 状态后，平台会在约 2–5 分钟内完成后处理（转录 → 脱敏 → 初稿生成）， 之后草稿出现在 Dashboard 的"采访记录 → 草稿列表"中。

草稿支持三种下载格式：

• markdown：适合直接复制到编辑器继续写作。
• docx：兼容 Word / WPS，含预设标题样式。
• json：结构化原始数据，适合接入自有 CMS（高级用户）。

也可通过 API 获取草稿：GET /v1/aij/interviews/{interviewId}/draft。

L2（增强合规）意味着：

• 采访中涉及身份证号、银行账号、医疗信息等敏感个人信息（P/Q/R 级）的对话片段， 由本地部署的 Qwen2.5:7b 模型处理，绝不上传云端 LLM。
• 草稿生成后，任何含敏感信息的段落会自动标记为"待人工审核"， 记者可在 Dashboard 的审核队列中查看和确认。
• 默认录音本地加密存储（local_encrypted），不同步至云端。

对采访流程的影响：生成草稿的时间比 L0/L1 多约 3–8 分钟（本地模型推理更慢）； 含敏感段落的草稿在人工审核完成前无法下载完整版本。

AIJ 使用 7 阶段状态机（OPENING → BACKGROUND → CORE_EVENT_A/B/C → CLOSING → ENDED）， 每个阶段内 AI 会根据受访者的回答动态选择 6 种追问策略之一， 问题顺序不是固定脚本，而是对话驱动的。

自定义方式：

• 初始提纲：通过 API 在创建采访时传入 outline 字段， AI 会以此为基础展开，而非完全自由发挥。
• 采访模板（高级）：在知识库中配置自定义采访模板， 可以精确控制每个阶段的核心追问方向。详见"知识库接入"文档（即将上线）。

是的。AIJ 支持受访者知情同意流程，在采访开始前会向受访者展示知情同意书 （内容可在 Dashboard 中自定义），同意书中应明确说明录音保留期限和删除权利。

受访者申请删除时，你可以调用 DELETE /v1/aij/interviews/{id}/recording 删除录音文件，同时保留采访的文字记录（如无异议）。若需删除全部数据， 调用 DELETE /v1/aij/interviews/{id}。 删除操作不可逆，会触发通知事件 interview.deleted。

是的。AiWma 在架构层面针对 PIPL 做了以下设计：

• 最小化采集：平台仅处理服务所需的最小数据集合，不做目的外的数据留存。
• L2+ 本地处理：敏感个人信息在本地模型中处理，不出境、不上云。
• 知情同意：AIJ 内置同意书流程，支持受访者撤回同意后立即触发数据删除。
• 数据保留期限：严格按 compliance.dataRetention 配置执行， 到期后自动删除原始数据，保留匿名化统计数据。

如需完整的数据处理协议（DPA）或合规报告，请联系商务团队获取。

默认不会。AiWma 平台在默认配置下不将客户的用户数据用于任何模型训练。 平台内部质量评估使用完全匿名化、人工合成的测试数据集。

如果你希望参与平台的"语音质量改进计划"（自愿），可在商务合同中注明， 届时平台会在明确的数据范围内（仅语音音频、不含转录文本）进行有限使用， 且需要额外签署数据授权协议。

AiWma 平台目前支持两种录音存储方式（在 services.aij.recording.storage 中配置）：

• local_encrypted：录音存储在你自己部署的服务器上（MinIO），AiWma 云端不保留原始录音文件。
• cloud：录音存储在 AiWma 的阿里云 OSS（华东节点），对象级加密（SSE-KMS），默认启用。

企业套餐用户可以在合同中指定使用自有的 OSS / S3 兼容存储， 届时平台只负责录音写入，不在 AiWma 侧留存副本。

默认不会中断。AiWma 采用弹性超量策略：当月会话数超过合同上限后， 平台继续提供服务，超量部分按合同约定的超量单价（overageRateCny）计费， 并通过告警渠道（邮件/Webhook）通知你的运营团队。

如果你需要硬性限制（超限后停止服务以控制成本）， 可以在合同中注明"硬上限"条款，或在 Dashboard 中手动开启"超限熔断"开关。

一次会话从用户第一条消息开始计量，以以下任一条件结束为止：

• 用户主动关闭对话窗口 → 会话状态 completed
• 超过最大会话时长（maxSessionDurationMinutes，默认 30 分钟）→ abandoned
• 超过最大轮次（maxTurnsPerSession，默认 60 轮）→ completed
• AI 主动转人工并结束会话 → completed

注意：用户只打开挂件但未发送任何消息，不计入会话用量。

不会。使用 aiwma_dev_ 前缀的开发环境 Key 发起的所有请求， 均路由至沙盒环境，不计入生产配额，也不触发超量计费。

开发环境的免费额度：每月 500 次 ACS 会话 + 20 次 AIJ 采访。 超出后该 Key 的请求会被拒绝（HTTP 429），但不影响生产 Key 的正常使用。

429 表示你的请求超过了速率限制（quota.apiCallsPerMinute）。建议实施指数退避重试：

// 基础等待时间 1s，最多重试 3 次，上限 30s
const wait = Math.min(1000 * 2 ** attempt + Math.random() * 500, 30000);
await new Promise(r => setTimeout(r, wait));

响应头中的 Retry-After 字段会告知最少等待秒数，可以直接读取该值：

const retryAfter = parseInt(response.headers.get("Retry-After") || "1");
await new Promise(r => setTimeout(r, retryAfter * 1000));

如果频繁触发限制，说明业务量增长，建议联系商务升级配额。

AI 回答质量通常由以下因素决定，按影响从大到小：

1. 知识库内容质量：最关键。确保 FAQ 条目覆盖高频问题，措辞与用户提问习惯一致。 RAG 文档要保持更新，避免过时信息。
2. 降低 temperature：ACS 场景建议 temperatureAcs: 0.2–0.35， 过高会增加创意但降低事实准确性。
3. 热词配置：在 asr.hotWords 中加入业务专有名词， 减少语音识别错误传递给 LLM 导致的理解偏差。
4. 开启后处理修正：asr.postCorrection.enabled: true 可自动修正 ASR 对领域词的误识别。

遇到具体错误案例，可以通过 Dashboard 的"会话详情"页面查看完整的对话日志和 AI 的内部推理， 这对定位问题根源非常有帮助。

平台状态页实时展示各服务节点的健康状况和历史事件：

• 状态页地址：status.aiwma.com
• 你也可以通过 API 自检：GET https://api.aiwma.com/health， 返回各微服务（gateway、engine、business 等）的状态。

建议在你自己的监控系统中将健康检查接口纳入定期拨测（建议间隔 30s）， 并通过 notifications.events 中的 system.error 事件订阅平台异常通知。

根据问题紧急程度选择联系方式：

• Dashboard 工单（推荐）：登录后点击右下角"?" → "提交工单"， 7×24 小时接收，SLA 响应时间：P0 紧急 ≤ 1h，P1 一般 ≤ 8h，P2 咨询 ≤ 48h。
• 邮件：support@aiwma.com，适合非紧急咨询和文档反馈。
• 企业微信群：商务经理在签约时会邀请你进入专属服务群， 企业套餐用户享有专属技术客户经理（TAM）1 对 1 支持。