实施附录

给实施和运维人员。这些都是可选项，不配也不影响主要功能；配了之后体验更完整。

备用模型、语音输入、发票识别优先在页面「开发 → 接入 → 模型服务」里配，保存即生效、不用重启，见 管理员篇。下面写的配置文件做法只作兜底：某个单位的某种用途在页面上一条都没配时才用。其余各项写在智能体服务的配置文件或环境变量里，密钥不要提交到代码仓库，改完重启智能体服务生效。

备用模型

解决什么：主模型限流、超时或出错时，员工反复看到「智能体当前使用的人比较多」。

怎么配：在模型服务页面的「对话」页签再新建一条，排在主模型后面。排第一的是主模型；它限流、超时或返回 5xx 时，先退避重试，再按顺序切到下一条。可以点「从业务系统同步」，把业务系统 AI 模块里已经配好的模型直接导进来，不用重复录密钥。

页面上一条对话模型都没配时，才用配置文件里的主模型和下面这组备用：

yudao:
  agentos:
    model:
      max-retries: 2          # 主模型先退避重试几次
      retry-backoff-ms: 800
      fallbacks:              # 再按顺序切备用模型
        - name: 内网模型
          base-url: http://<内网推理服务>
          api-key: <密钥，没有就填 none>
          model: <模型名>

要注意什么：页面上配了对话模型以后，这个单位就不再用配置文件里的对话模型，备用也要在页面上排。

怎么验证：每条点「自测」都显示「通过」；「开发 → 授权与运营」里「限流」次数明显下降；工作台提问能答出正文。

语音输入

解决什么：员工点输入框下方的话筒说话转文字。

怎么配：在模型服务页面的「语音转写」页签新建一条，接任一兼容 OpenAI 语音转写接口（/audio/transcriptions）的服务。可以自建开源语音识别服务（如 SenseVoice），提供 OpenAI 兼容转写接口即可。只用排第一的那条，不自动切换。页面上没配时，用配置文件里的：

yudao:
  agentos:
    asr:
      base-url: ${AGENTOS_ASR_URL}
      api-key: ${AGENTOS_ASR_KEY}
      model: ${AGENTOS_ASR_MODEL}

不配时，员工点话筒会提示改用文字输入。

怎么验证：在工作台点话筒，说一句「我还有哪些待办」，文字出现在输入框里。浏览器需要允许麦克风权限，且页面要用 https 访问。

外部资讯源

解决什么：「管理 → 外部洞察」按企业画像归纳行业、政策、竞对资讯。

怎么配：

yudao:
  agentos:
    insight:
      search-url: https://<资讯检索服务>/api?q={q}   # {q} 是检索词占位
      api-key-header: <鉴权请求头名，不需要可不填>
      api-key: <密钥>

检索接口返回 JSON，结果数组放在 results、items、data、organic 任一字段，每条至少有 title。

怎么验证：管理者在「外部洞察」填好企业画像，点「刷新洞察」，每类资讯带来源篇数。未配置时页面显示配置指引，不会凭空生成资讯。

企业微信、钉钉、飞书机器人入口

解决什么：员工在企业 IM 里直接和智能体对话。

怎么配：

yudao:
  agentos:
    channel:
      token: ${AGENTOS_CHANNEL_TOKEN}   # 与机器人回调配置里的凭证一致

留空时入口关闭，所有来自机器人的请求都会被拒绝并提示「通道凭证无效」。

要注意什么：机器人那边要能把员工身份对应到业务系统账号；凭证泄露时立即更换。

发票识别

解决什么：费用报销助手识别员工上传的发票，预填报销单。

怎么配：在模型服务页面的「OCR 识别」页签新建一条，平台选 PaddleOCR，填识别服务地址、令牌和模型名；业务系统 AI 模块里已经有 OCR 模型的，直接「从业务系统同步」。只用排第一的那条，不自动切换：识别不出来多半是图片本身的问题，换模型通常也识别不出。

页面上没配时，用配置文件里的：

yudao:
  agentos:
    ocr:
      url: ${AGENTOS_OCR_URL}
      model: ${AGENTOS_OCR_MODEL}
      token: ${AGENTOS_OCR_TOKEN}

两边都没配时，员工上传发票会提示「发票识别服务还没配好」，不会改任何单据。

怎么验证：在 OCR 页签点「自测」，系统用内置的一张示例发票去识别，显示「通过：识别出示例发票号码 …」。

授权书

解决什么：按合同约定的客户、席位数和到期日启用智能体。

怎么做：

1. 我方签发授权书正文和验签公钥。

2. 公钥写进配置，并打开校验：

   yudao:
     agentos:
       license:
         enabled: true
         public-key: <我方提供的验签公钥>

3. 重启后，实施人员用智能体管理员身份调用导入接口，提交授权书正文：

   POST /admin-api/agentos/commercial/import-license

4. 在「开发 → 授权与运营」核对客户、版本、席位、到期日。

你会看到：

要注意什么：

• 交付环境必须打开校验；页面显示「未开启校验」说明还没打开。
• 授权书改动任何一个字符都会验签失败，不要手工编辑；续期请换新的授权书。
• 席位按当月用过智能体的员工计算。席位占满后，新员工会被提示席位已满。
• 到期后有 7 天宽限期，期间持续提示续期；宽限期结束后不能发起新对话，历史记录仍可查看。

失控防护

默认已开启，一般不用改：

yudao:
  agentos:
    guard:
      max-input-tokens: 16000
      max-turns-per-conversation: 100

不建议关闭。 模型反复查同一个接口是常见情况，这道闸门能防止一次死循环用掉大量模型额度。