OpenAvatarChat 配置指南：从 --config 到 Handler 参数的完整解析

本文以 OpenAvatarChat 的配置体系为主线，系统讲解程序启动时配置文件的选择、全局参数（logger / service / chat_engine）的语义与默认值，以及 Handler 级配置的组织方式与生效机制。读完本文，你将能读懂仓库内任意一份 YAML 配置（如 config/chat_with_openai_compatible.yaml、config/chat_with_lam.yaml），并根据实际场景自行组合 ASR、LLM、TTS、VAD、Avatar 等模块。

配置加载入口：--config 参数

OpenAvatarChat 在启动时通过命令行 --config 参数指定配置文件，标准启动命令为：

uv run src/demo.py --config <path-to-config>.yaml

从 demo.py 的 parse_args 可以看到完整参数定义：

• --config：配置文件路径，默认值为 config/chat_with_openai_compatible_bailian_cosyvoice.yaml；
• --host / --port：可选地覆盖服务监听地址与端口（优先级低于配置文件中的 service 段，见下文加载顺序）；
• --env：配置文件内使用的环境（environment）名称，默认 default。

--config 也可以被环境变量 OPEN_AVATAR_CHAT_CONFIG 覆盖，见 demo.py 中 main() 的逻辑：

config_from_env = os.environ.get("OPEN_AVATAR_CHAT_CONFIG", None)
if config_from_env:
    args.config = config_from_env

也就是说，配置来源的优先级为：环境变量 OPEN_AVATAR_CHAT_CONFIG > 命令行 --config > 默认值。

配置文件的解析过程

配置加载实现在 service_config_loader.py 的 load_configs 函数，关键流程如下：

1. 将 --env 写入环境变量 ENV_FOR_DYNACONF，并基于项目根目录解析配置路径（支持绝对路径或相对路径）；
2. 若配置文件不存在，直接打印错误并 exit(1)；
3. 使用 Dynaconf 读取 YAML，开启 environments=True 与 load_dotenv=True，因此配置文件中可以按环境分层（如 default 段），且可以从工作目录的 .env 文件读取环境变量；
4. 将解析结果分别校验（model_validate）为三个 Pydantic 模型：LoggerConfigData、ServiceConfigData、ChatEngineConfigModel。

最终这三个配置对象分别被用于日志初始化、uvicorn 服务启动与 ChatEngine 的初始化，见 demo.py。

全局参数总览

--config 指定的 YAML 顶层包含三大段：logger、service、chat_engine。官方配置文档给出的参数与默认值如下：

参数	默认值	说明
log.log_level	INFO	日志级别
service.host	0.0.0.0	服务监听地址
service.port	8282	服务监听端口
service.cert_file	ssl_certs/localhost.crt	SSL 证书文件路径
service.cert_key	ssl_certs/localhost.key	SSL 密钥文件路径
chat_engine.model_root	models	模型根目录
chat_engine.handler_configs	N/A	各 Handler 的可配置项

[!IMPORTANT] 所有路径参数都可以使用绝对路径，或相对于项目根目录的相对路径。

配置文件结构速览

以仓库中开箱即用的 chat_with_openai_compatible.yaml 为例，完整骨架为：

default:
  logger:
    log_level: "INFO"
  service:
    host: "0.0.0.0"
    port: 8282
    cert_file: "ssl_certs/localhost.crt"
    cert_key: "ssl_certs/localhost.key"
  chat_engine:
    model_root: "models"
    handler_search_path:
      - "src/handlers"
    handler_configs:
      # ... 各 Handler 配置

注意顶层 default: 是 Dynaconf 的环境名，对应启动时的 --env default。

logger 段：日志级别

logger.log_level 由 LoggerConfigData 定义（默认 INFO），见 logger_config_data.py。在 logger_utils.py 中，它会移除默认日志处理器并重新绑定到 stdout，同时额外写入 logs/log.log（10 MB 滚动、保留 10 份、UTF-8 编码、异步队列）。支持 DEBUG、INFO、WARNING、ERROR 等常用级别。

service 段：监听地址、端口与 TLS

service 段对应 ServiceConfigData（见 service_config_data.py），字段语义如下：

字段	默认值	说明
host	127.0.0.1	监听地址，文档默认 0.0.0.0（对外暴露）
port	8080	监听端口，仓库配置默认 8282
cert_file	无	SSL 证书路径，仓库配置默认 ssl_certs/localhost.crt
cert_key	无	SSL 私钥路径，仓库配置默认 ssl_certs/localhost.key

其用途为构造 uvicorn 配置（demo.py），SSL 上下文由 create_ssl_context 生成。WebRTC 会话需要 HTTPS，证书生成可参考 scripts/create_ssl_certs.sh，本地开发也直接使用仓库内置占位说明文件 ssl_certs/put_ssl_certs_here.txt 对应的路径。

chat_engine 段：模型目录与 Handler 装配

chat_engine 段是配置的核心，对应 ChatEngineConfigModel（见 chat_engine_config_data.py）：

字段	默认值	说明
model_root	""（空串）	模型根目录，配置示例中为 models
concurrent_limit	1	引擎并发上限，如 LAM 配置中设为 5
handler_search_path	[]	Handler 模块搜索路径列表
logic_search_path	[]	Logic 模块搜索路径列表
handler_configs	无	各 Handler 的配置字典
logic_configs	无	各 Logic 的配置字典
outputs	{}	引擎输出通道到数据源的映射
turn_config	无	轮次控制相关配置

其中 model_root 还参与 modelscope 缓存目录的设置：若 model_root 为相对路径，demo.py 会将其（去掉 models 前缀后的部分）拼接到项目目录并写入环境变量 MODELSCOPE_CACHE，引导模型下载到指定位置。

handler_search_path 与 handler_configs 的配合是理解整个配置体系的关键：HandlerManager（handler_manager.py）会遍历 handler_search_path 加入 sys.path，然后逐个读取 handler_configs 中的条目，用 HandlerBaseConfigModel 校验并跳过 enabled: false 的 Handler，最终通过 module 字段导入对应的 Handler 类并注册实例。因此配置中每个 Handler 至少需要 module 字段，例如：

RtcClient:
  module: client/rtc_client/client_handler_rtc

HandlerBaseConfigModel 还提供三个通用控制项（见 chat_engine_config_data.py）：

• enabled：默认 true，置为 false 可整段关闭该 Handler；
• concurrent_limit：默认 1，控制该 Handler 的并发实例数；
• input_type_override / output_type_override：用于双工（duplex）模式的信号类型覆盖，格式为 {"原始类型名": "目标类型名"}，例如 {"HUMAN_AUDIO": "HUMAN_DUPLEX_AUDIO"}。

Handler 配置的组织方式

chat_engine.handler_configs 是一个以 Handler 名为键、配置项为值的字典。Handler 名称即配置文件中的键名（如 RtcClient、SileroVad、SenseVoice、CosyVoice、LLMOpenAICompatible、LiteAvatar 等），module 字段是相对 handler_search_path 的模块路径。

以 chat_with_lam.yaml 中的典型段落为例：

handler_configs:
  LamClient:
    module: client/ws_lam_client/ws_lam_client_handler
    asset_path: "lam_samples/barbara.zip"
    connection_ttl: 900
    upstream_mode: 'ws'
  SileroVad:
    module: vad/silerovad/vad_handler_silero
    speaking_threshold: 0.15
    start_delay: 2048
    end_delay: 5000
    buffer_look_back: 5000
    speech_padding: 512
    volume_threshold: -30

可见 asset_path、connection_ttl、speaking_threshold 等字段都是各 Handler 自定义的业务参数，由对应 Handler 类的配置模型在运行时解析。每个 Handler 的具体参数说明，官方文档统一收录在 Handler 参考中，入口为 Handler 参考索引（中文版见 handlers/index.md）。

各类 Handler 参考入口

• Client：RTC 客户端 rtc-client、LAM 客户端 lam-client
• ASR：SenseVoice sensevoice
• LLM：OpenAI 兼容接口 openai-compatible、Qwen-Omni qwen-omni、Dify dify
• TTS：百炼 CosyVoice bailian-cosyvoice、本地 CosyVoice cosyvoice-local、Edge TTS edge-tts
• VAD：SileroVAD silero-vad、Smart Turn（双工）smart-turn
• Avatar：LiteAvatar liteavatar、LAM lam、MuseTalk musetalk、FlashHead flashhead
• Agent：多轮工具调用 Agent（Beta）chat-agent
• Manager：实时会话监控与信号流可视化 data-tool

实战：以 OpenAI 兼容 LLM Handler 为例

下面以 openai-compatible 文档中的配置为例，演示 handler_configs 内一个典型 Handler 的写法：

LLMOpenAICompatible:
  model_name: "qwen-plus"
  system_prompt: "You are an AI digital human."
  api_url: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
  api_key: 'yourapikey'

参数	默认值	说明
LLMOpenAICompatible.model_name	qwen-plus	使用的模型名
LLMOpenAICompatible.system_prompt	（空）	系统提示词
LLMOpenAICompatible.api_url	（空）	OpenAI 兼容 API 的 URL
LLMOpenAICompatible.api_key	（空）	API Key

[!TIP] OpenAvatarChat 会从工作目录读取 .env 文件中的环境变量（Dynaconf 的 load_dotenv=True）。因此 api_key 往往可以留空，改用环境变量注入密钥，避免密钥写入配置文件。

仓库配置示例中该 Handler 还有更多实用参数，例如 enable_video_input（是否启用视频输入，需模型支持）、history_length（历史对话轮数）等，并注释了多种可选 api_url（阿里云 DashScope 兼容模式、Ollama 本地 http://127.0.0.1:11434/v1、Google Gemini 兼容端点等），见 chat_with_openai_compatible.yaml。结合上文的 input_type_override / output_type_override，双工模式（duplex）配置示例见仓库内的 chat_with_openai_compatible_bailian_cosyvoice_duplex.yaml 等文件。

常见问题与排查思路

配置文件找不到：load_configs 会在启动时报错 Config file ... not found! 并退出，请检查 --config 路径是否为绝对路径或相对项目根目录的路径。

Handler 未生效：确认该 Handler 段内 enabled 不为 false，且 module 路径能在 handler_search_path 指定的目录下解析；HandlerManager 会打印导入失败或跳过的日志。

HTTPS/证书问题：WebRTC 依赖 HTTPS，请确保 service.cert_file / service.cert_key 指向有效证书；本地调试可参考 scripts/create_ssl_certs.sh 生成自签名证书。

日志看不到输出：logger.log_level 只影响 stdout 与 logs/log.log 两个输出端（见 logger_utils.py），将级别调低（如 DEBUG）可获取更细的调试信息。

更多开箱即用配置：仓库 config 目录提供了十余份完整配置，覆盖本地 CosyVoice、百炼 CosyVoice、Edge TTS、MuseTalk、FlashHead、LAM 双工、Agent 等组合，可作为自定义配置的直接模板。

总结

OpenAvatarChat 的配置体系分层清晰：logger / service 控制运行环境，chat_engine 控制引擎与模块装配，handler_configs 内逐 Handler 展开业务参数。理解 --config、--env、环境变量 OPEN_AVATAR_CHAT_CONFIG 三者的优先级与 Dynaconf 的解析流程，再结合 HandlerManager 的导入注册机制，即可对任意现有配置进行增删改与调试，并借助 Handler 参考文档与 config 目录模板快速搭建新的对话方案。