客户配置文件

client.yaml 是 AiWma 平台中每个客户实例的"总控文件"。它声明了该客户开通了哪些服务、外观如何呈现、AI 模型和语音引擎如何工作、合规等级要求，以及用量上限。本文将逐一解释每个顶级配置段的含义，帮助你快速理解并定制自己的实例。

谁来修改这个文件？ 通常由 AiWma 商务团队在签约后与你共同完成初始配置。中高级用户可在 Dashboard 中实时预览变更效果，提交后经平台验证再生效；不会直接在服务器上手动编辑 YAML 文件。

完整结构一览

下面是一份典型的 client.yaml 骨架，展示了所有顶级字段及其层级关系：

client.yaml（结构骨架）

meta:            # 客户元信息与合同标识
  clientCode: "XM001"
  clientName: "仙匣互动信息技术有限公司"
  contractId:  "CT-2026-00042"
  version:     "1.4.0"
  lastUpdated: "2026-05-28"
  status:      "active"          # active | suspended | trial

services:        # 开通的产品线
  acs:           #   AI 客服（可选）
    enabled: true
    tier: "pro"
    ...
  aij:           #   AI 采访（可选）
    enabled: true
    tier: "basic"
    ...

brand:           # 外观与欢迎语定制
  displayName:  "仙匣智能客服"
  botNameAcs:   "晓仙"
  ...

llm:             # 大语言模型策略
  modelPrimary: "claude-sonnet-4-6"
  ...

asr:             # 语音识别（ASR）配置
  providerPrimary: "deepgram"
  ...

tts:             # 语音合成（TTS）配置
  providerPrimary: "cosyvoice2"
  ...

knowledge:       # 知识库与数据源
  acsKnowledgeBase:
    type: "hybrid"
    ...
  aijKnowledgeBase:
    ...

tools:           # 外部工具调用（可选）
  - name: "order_query"
    ...

compliance:      # 合规等级与数据保留
  piiProcessing:
    level: "L1"
  ...

notifications:   # 告警与事件通知
  channels:
    email: ...
    webhook: ...

quota:           # 用量上限
  acsSessionsPerMonth: 50000
  ...

meta · 元信息

标识这份配置属于哪个客户、对应哪份合同、当前处于什么状态。

字段	类型	说明
`clientCode`	string	平台分配的唯一客户代码，用于 API Key 中段。格式：大写字母 + 数字，如 `XM001`
`clientName`	string	企业全称，用于账单与邮件通知的显示
`contractId`	string	合同编号，平台内部追踪用，变更须联系商务
`version`	string	配置版本号（语义化），每次变更自动递增
`lastUpdated`	date	最近一次生效时间（ISO 8601 格式）
`status`	enum	`active` 正常运行 · `trial` 试用期 · `suspended` 暂停

services.acs · AI 客服服务

控制 ACS 产品是否开启、套餐档位、会话限额与支持的渠道。

services.acs 示例

services:
  acs:
    enabled: true
    tier: "pro"           # starter | pro | enterprise
    quota:
      sessionsPerMonth: 50000          # 月会话上限
      overageRateCny: 0.08             # 超出后每会话单价（元）
      maxSessionDurationMinutes: 30    # 单次会话最长时长
      maxTurnsPerSession: 60           # 单次会话最大轮次
    channels:
      - "web_widget"                   # 网页挂件
      - "api_direct"                   # 直接 API 调用
      # - "phone"                      # 电话通道（需单独开通）
    language:
      primary: "zh-CN"
      fallback: "en"
      mixedAllowed: true               # 允许中英文混搭
    handover:
      enabled: true
      triggerIntents:
        - "COMPLAINT_ESCALATE"
        - "HUMAN_REQUEST"
      handoverTarget: "https://your-crm.example.com/webhook/handover"
      handoverMessage: "正在为您转接人工客服，请稍候……"

渠道选择建议 初次接入推荐只开启 web_widget，稳定后再逐步添加其他渠道。每个渠道对应不同的计费权重：网页组件 × 1.0，语音电话 × 2.5。

services.aij · AI 采访服务

控制 AIJ 产品的开启状态、套餐、采访类型权限与录音存储方式。

services.aij 示例

services:
  aij:
    enabled: true
    tier: "basic"          # single | basic | pro
    quota:
      interviewsPerMonth: 200
      singleSessionMaxMinutes: 90
      draftVersionsPerInterview: 5
    interviewTypes:
      - "SPEAK"            # 维权/敏感采访（L2 合规）
      - "INDIE"            # 开发者独立访谈
    complianceLevels:
      SPEAK: "L2"
      INDIE: "L1"
    outputFormats:
      - "markdown"
      - "docx"
    recording:
      enabled: true
      storage: "local_encrypted"   # local_encrypted | cloud
      retentionDays: 180
      cloudSync: false

套餐	月采访数	可用类型	说明
single	10 次	SHOW	展会快报，最轻量
basic	200 次	SHOW · INDIE · MONEY	大多数媒体机构起步套餐
pro	无限制	全部 4 种	含 SPEAK（维权，L2 合规）

brand · 品牌外观

控制对话界面中所有可见的品牌元素——名称、头像 URL 和颜色。

brand 示例

brand:
  displayName:      "仙匣智能助手"      # 对话窗口标题栏显示名
  botNameAcs:       "晓仙"              # 客服机器人昵称
  botNameAij:       "AiJ 记者"          # 采访机器人昵称
  avatarAcs:        "https://cdn.example.com/avatar-acs.png"
  avatarAij:        "https://cdn.example.com/avatar-aij.png"
  colorPrimary:     "#1B3A5C"           # 主色（导航栏、按钮）
  colorAccent:      "#E8703A"           # 强调色（高亮、链接）
  colorSurface:     "#FFFFFF"           # 气泡背景色
  welcomeMessageAcs: "你好！我是晓仙，有什么可以帮助您的吗？"
  welcomeMessageAij: "您好，我是 AiJ 记者，本次采访将全程加密录音……"

头像图片推荐使用 HTTPS CDN 地址，尺寸建议 96×96 px PNG（圆角由前端自动处理）。颜色支持 6 位十六进制格式。品牌配置变更后通常在 5 分钟内自动热重载，无需重启。

llm · 大语言模型策略

声明主力模型、备用模型（降级）和本地模型（离线/合规场景），以及各场景的生成参数。

llm 示例

llm:
  providerPrimary: "anthropic"
  modelPrimary:    "claude-sonnet-4-6"    # 主力云端模型
  providerFallback: "openai"
  modelFallback:   "gpt-4o-mini"          # 主力不可用时自动切换
  providerLocal:   "ollama"
  modelLocal:      "qwen2.5:7b"           # 本地模型，处理 L2/L3 敏感数据
  temperatureAcs:  0.3                    # 客服场景：更稳定、确定性更强
  temperatureAij:  0.7                    # 采访场景：更有弹性、追问更自然
  maxTokensAcs:    512
  maxTokensAij:    2048
  timeoutSeconds:  30
  retryAttempts:   2
  promptCaching:
    enabled: true
    cacheSystemPrompt: true
    cacheTtlMinutes: 5
  costAlertThresholdCnyPerDay: 500        # 每日费用超限告警阈值（元）

关于本地模型 modelLocal 仅在以下情况自动启用：合规等级为 L2 或 L3 的数据段、以及云端主力模型连续超时后的最后降级。使用本地模型需要在部署服务器上预先拉取对应模型文件。

asr · 语音识别

配置将用户语音转换为文字的引擎，包括主力云服务、本地降级和声音活动检测（VAD）参数。

asr 示例

asr:
  providerPrimary: "deepgram"
  modelPrimary:    "nova-3"
  language:        "zh-CN"
  localFallback:
    enabled: true
    provider: "sherpa-onnx"
    model:    "paraformer-zh"
    trigger:  "cloud_unavailable"    # always | cloud_unavailable | sensitive_data
  vad:
    provider:      "silero"
    sensitivity:   0.5               # 0.0（宽松）~ 1.0（严格），建议 0.4–0.6
    minSilenceMs:  600               # 静音多少毫秒视为说话结束
    minSpeechMs:   200               # 至少多少毫秒才算有效语音
  hotWords:
    - "人工客服"
    - "退款"
    - "投诉"
  postCorrection:
    enabled: true
    model: "qwen2.5:7b"             # 对识别结果做领域词修正

参数	推荐值	影响
`vad.sensitivity`	0.5	过低漏检噪音中的语音；过高误截有效语音
`vad.minSilenceMs`	600 ms	值越小响应越快，但易截断长句；建议不低于 400 ms
`hotWords`	业务关键词	提升特定词汇的识别精度，建议控制在 50 词以内

tts · 语音合成

配置将 AI 文字回复转换为语音的引擎，以及客服和采访场景分别使用的音色。

tts 示例

tts:
  providerPrimary:  "cosyvoice2"
  voiceAcs:         "zh-CN-Xiaoxiao"    # 客服音色：女声，亲切
  voiceAij:         "zh-CN-Yunyang"     # 采访音色：男声，沉稳
  providerFallback: "edge-tts"
  voiceFallbackAcs: "zh-CN-XiaoxiaoNeural"
  voiceFallbackAij: "zh-CN-YunxiNeural"
  speed:            1.05                # 语速倍率，1.0 = 正常
  pitchAdjustment:  0.0                 # 音调微调（-1.0 ~ +1.0）
  emotionEnabled:   true                # 情感韵律增强（CosyVoice 2 专属）

CosyVoice 2 的 emotionEnabled 开启后，引擎会根据上下文语境自动为语音添加轻微的情感变化（如安慰、鼓励、正式感）。这对客服场景的用户体验提升显著，但会增加约 80 ms 的额外延迟。

knowledge · 知识库

声明 ACS 和 AIJ 各自使用的知识来源——结构化 FAQ、RAG 向量库，或实时 API 查询。

knowledge 示例

knowledge:
  acsKnowledgeBase:
    type: "hybrid"             # structured | rag | hybrid
    structuredFaq:
      source: "s3://bucket/faq.jsonl"
      refreshCron: "0 3 * * *"           # 每天凌晨 3 点刷新
    ragDocuments:
      vectorDb:        "qdrant"
      collection:      "xm001_acs_docs"
      embeddingModel:  "text-embedding-3-small"
      chunkSize:       512
      sources:
        - "s3://bucket/product-manuals/"
        - "s3://bucket/policy-docs/"
    realtimeApi:
      enabled: true
      endpoint: "https://api.example.com/order-status"
      authHeader: "X-Api-Key"
      capabilities:
        - "order_query"
        - "inventory_check"

  aijKnowledgeBase:
    interviewTemplates:
      source: "s3://bucket/aij/templates/"
    sourceMaterials:
      vectorDb:   "qdrant"
      collection: "xm001_aij_sources"
      sources:
        - "s3://bucket/aij/background-docs/"
    complianceRules:
      source: "s3://bucket/aij/compliance/"

知识库类型	适合场景	检索速度	维护成本
`structured`	内容有限、高度标准化的 FAQ	极快	低
`rag`	大量非结构化文档	中等	中
`hybrid`	兼顾 FAQ 命中率与长尾覆盖	快	中高

tools · 外部工具调用

让 AI 在对话中实时调用你的业务接口——查询订单状态、查库存、查物流等。每个工具定义为一条规则，AI 会在判断用户意图后自动决定是否调用。

tools 示例

tools:
  - name: "order_query"
    description: "根据订单号查询订单状态和物流信息"
    endpoint:    "https://api.example.com/orders/{orderId}"
    authRequired: true
    scope: "acs"           # acs | aij | both

  - name: "product_search"
    description: "根据关键词在商品库中检索产品信息"
    endpoint:    "https://api.example.com/products/search"
    authRequired: false
    scope: "acs"

工具接口安全要求 所有 authRequired: true 的工具接口的 API Key 或 Token 需通过 Dashboard 的"密钥管理"页面单独配置，不写入 YAML 明文。工具接口的响应时间建议控制在 2 秒内，超时会触发降级提示。

compliance · 合规配置

声明数据处理的合规等级，控制哪些类型的个人信息在本地处理、哪些触发人工审核，以及各类数据的保存期限。

compliance 示例

compliance:
  piiProcessing:
    level:           "L1"          # L0 | L1 | L2 | L3
    localModel:      "qwen2.5:7b"  # L2+ 时，敏感数据由本地模型处理
    stripBeforeCloud: true         # 上传云端前脱敏
    pGrade: ["name", "phone", "id_number"]       # 人工脱敏字段
    qGrade: ["address", "bank_account"]          # 模糊化字段
    rGrade: ["medical_history", "political_view"] # 完全本地处理字段

  contentReview:
    autoCheck:            true
    model:                "qwen2.5:7b"
    humanReviewTriggers:
      - "SENSITIVE_TOPIC"
      - "LOW_CONFIDENCE"
      - "USER_COMPLAINT"
    reviewQueue:   "https://review.example.com/webhook"
    reviewSlaHours: 24

  dataRetention:
    sessionDataDays:          90   # 客服会话记录保留天数
    interviewDataDays:       180   # 采访记录保留天数
    recordingDays:           180   # 录音文件保留天数
    anonymizedAnalyticsDays: 730   # 匿名化分析数据保留天数

合规等级	数据处理方式	典型场景
L0 基础	全量上云	展会资讯、公开活动
L1 标准	P 级字段本地脱敏后上云	普通商务客服、融资报道
L2 增强	P/Q/R 级字段本地模型处理，不进云	维权采访、金融客服
L3 最高	所有 AI 推理本地完成	医疗、司法等高敏感场景

notifications · 通知与告警

配置平台事件（如用量超限、审核触发、系统异常）通过哪些渠道发送给运营团队。

notifications 示例

notifications:
  channels:
    email:
      provider:    "sendgrid"
      from:        "noreply@aiwma.com"
      recipients:
        ops:     "ops@example.com"
        billing: "billing@example.com"
    webhook:
      enabled:   true
      endpoint:  "https://your-ops.example.com/aiwma-events"
      secretEnv: "AIWMA_WEBHOOK_SECRET"   # 在服务器环境变量中设置

  events:
    - event: "quota.warning"       # 用量达到阈值
      channels: ["email", "webhook"]
      priority: "normal"
    - event: "quota.exceeded"      # 用量超限
      channels: ["email", "webhook"]
      priority: "urgent"
    - event: "session.handover"    # 转人工触发
      channels: ["webhook"]
    - event: "content.flag"        # 内容审核触发
      channels: ["email", "webhook"]
      priority: "normal"
    - event: "system.error"        # 服务异常
      channels: ["email", "webhook"]
      priority: "urgent"

quota · 用量配额

声明全局用量上限，平台在达到阈值时发出告警，超限时自动限流（而非中断服务）。

quota 示例

quota:
  acsSessionsPerMonth:   50000   # ACS 月会话数上限
  aijInterviewsPerMonth:   200   # AIJ 月采访数上限
  storageGb:               100   # 对象存储（录音 / 文档）上限，单位 GB
  apiCallsPerMinute:       500   # API 调用频率上限（全渠道合计）
  concurrentSessionsMax:    50   # 同时并发会话数上限
  alertThresholdPct:        80   # 到达多少百分比时触发告警通知

超限行为 当月用量达到上限后，平台默认启用弹性超量策略：继续服务，但按超量单价计费（见 services.acs.quota.overageRateCny）。如果希望硬停服务，请联系商务在合同中注明"硬上限"条款。

配置变更生效流程

1

在 Dashboard 修改

登录 AiWma 控制台，进入"配置 → 客户配置"，通过表单或 YAML 编辑器修改目标字段。
2

平台验证

提交后，平台会在约 10 秒内对配置进行 Schema 校验和安全审查，校验失败会显示具体错误字段，不会影响当前运行中的配置。
3

热重载生效

验证通过后，配置在 5 分钟内热重载至所有服务节点，无需停机。品牌外观类变更（brand、tts.voice）立即生效；模型策略类变更（llm、asr）在新会话中生效。
4

查看版本历史

所有配置变更自动记录版本快照，支持一键回滚至任意历史版本（最多保留 30 个快照）。

配置常见问题

错误提示	原因	解决方法
`INVALID_CLIENT_CODE`	`meta.clientCode` 与合同档案不符	联系商务确认正确的客户代码
`TIER_NOT_AUTHORIZED`	使用了未开通套餐对应的功能（如 SPEAK 类型需 pro 套餐）	升级套餐或移除对应配置项
`QUOTA_EXCEEDS_CONTRACT`	`quota.*` 中填写的数值超过合同约定上限	与商务协商调整合同配额
`TOOL_ENDPOINT_UNREACHABLE`	工具接口验证时无法访问	检查 endpoint URL 及服务器防火墙规则
`AVATAR_URL_INVALID`	头像 URL 非 HTTPS 或返回非图片内容	改用 HTTPS CDN 地址，确保 MIME 类型为 `image/*`

客户配置文件

完整结构一览

meta · 元信息

services.acs · AI 客服服务

services.aij · AI 采访服务

brand · 品牌外观

llm · 大语言模型策略

asr · 语音识别

tts · 语音合成

knowledge · 知识库

tools · 外部工具调用

compliance · 合规配置

notifications · 通知与告警

quota · 用量配额

配置变更生效流程

在 Dashboard 修改

平台验证

热重载生效

查看版本历史

配置常见问题