TEN Framework 语音情感健康分析实战：Thymia Analyzer Python 扩展详解

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本篇技术指南围绕 TEN Framework面向会话式语音 AI Agent 的开源框架中的thymia_analyzer_python扩展展开讲解如何在不打断对话的前提下实时缓冲用户语音、通过 Voice Activity DetectionVAD过滤静音并将语音发送至 Thymia Mental Wellness API 进行情绪状态分析最终以 LLM Tool 的形式按需向大模型提供 distress、stress、burnout、fatigue、self-esteem 等健康指标。读完本文你将掌握该扩展的配置方法、图graph接线方式、LLM 工具调用契约以及其底层音频缓冲与 API 轮询的实现原理可直接在 TEN 语音 Agent 项目中复现这套无感陪伴式心理健康监测能力。扩展是什么在语音对话中做无声的情绪监测thymia_analyzer_python是 TEN Framework 官方 Agent 仓库中提供的一个 Python 扩展位于 ai_agents/agents/ten_packages/extension/thymia_analyzer_python/它把一条旁路音频流从对话中复制出来在后台持续分析说话人的语音特征输出一组 0~10 量表的心理健康指标。它的核心设计是后台运行、不打断对话实时音频缓冲在会话进行中持续接收 PCM 音频帧边收边积累语音活动检测VAD用 RMS均方根音量阈值智能过滤静音段只保留真正有效的语音Thymia API 分析攒够最低语音时长后将音频上传到 Thymia Mental Wellness API 做健康分析LLM 工具注册以get_wellness_metrics工具的形式注册给大模型LLM 可以在合适的语境下按需拉取指标优雅降级API 不可用时静默失败绝不破坏正常对话流程隐私友好默认使用匿名用户标签数据采集行为可配置持续监测一个会话内支持多次分析默认最多 10 次。从源码看该扩展的类层次为ThymiaAnalyzerExtension继承自AsyncLLMToolBaseExtensionextension.py并通过 addon.py 中的register_addon_as_extension(thymia_analyzer_python)完成注册。这意味着它天然具备异步扩展 LLM 工具双重能力既处理音频帧数据又能响应大模型的工具调用。配置参数必填项、可选项与默认值扩展的配置通过图graph节点属性下发由扩展在on_start阶段用ten_env.get_property_*系列接口读取extension.py。参数类型声明在 manifest.json 的api.property.properties中仓库内默认值集中在 property.json。必填项参数类型说明api_keystringThymia API 密钥支持环境变量注入如${env:THYMIA_API_KEY}。未配置时扩展会直接禁用源码中on_start会记录Thymia API key not configured - extension will be disabled并跳过初始化见 extension.py。可选项参数类型默认值说明min_speech_durationfloat6430.0触发分析所需的最少有效语音秒数不含前后静音填充。silence_thresholdfloat640.02VAD 的 RMS 阈值归一化到 0~1高于该值视为有人说话。continuous_analysisbooltrue是否在整个会话中持续分析关闭则只分析一次。min_interval_secondsint6460两次分析之间的最小间隔秒数。max_analyses_per_sessionint6410单会话分析次数上限防止无限调用第三方 API。poll_timeoutint6460等待 API 结果的最大秒数README 标注 120仓库 property.json 与源码默认值为 60。poll_intervalint645结果轮询间隔秒数。analysis_modestringdemo_dual分析模式hellos_only仅 5 项健康指标或demo_dual健康指标 Apollo 抑郁/焦虑临床指标。apollo_mood_durationfloat6420.0demo_dual 模式下情绪问答语音时长源码级默认常量为 30.0见 extension.py。apollo_read_durationfloat6420.0demo_dual 模式下朗读语音时长源码默认常量 30.0。需要特别注意的是min_speech_duration判断的是扣除静音后的有效语音时长源码中AudioBuffer.has_enough_speech()基于actual_speech_duration而非含填充的总时长见 extension.py因此 30 秒的分析门槛实际对应的是用户真正开口说话的累计时长。图Graph配置三步接入语音 Agent在应用的property.json中把扩展加入图节点并完成音频路由与工具注册三条链路。第一步声明扩展节点{ nodes: [ { type: extension, name: thymia_analyzer, addon: thymia_analyzer_python, extension_group: default, property: { api_key: ${env:THYMIA_API_KEY}, min_speech_duration: 30.0 } } ] }环境变量引用采用${env:THYMIA_API_KEY}语法密钥不会以明文出现在配置仓库中。第二步音频分流——一份 PCM 帧喂给 STT 和 Thymia对话音频需要同时流向语音识别STT与本扩展在音频适配节点上配置多目标分发{ extension: streamid_adapter, audio_frame: [{ name: pcm_frame, dest: [ {extension: stt}, {extension: thymia_analyzer} ] }] }扩展在manifest.json中声明了名为pcm_frame的audio_frame_in输入manifest.json并在 on_audio_frame 中通过lock_buf()读取 PCM 字节流交给AudioBuffer。值得注意的是同一份音频同时用于转写与健康分析STT 流程完全不受影响。第三步LLM 工具注册把thymia_analyzer注册为 LLM 工具源大模型即可在对话中调用健康指标{ extension: main_control, cmd: [{ names: [tool_register], source: [ {extension: thymia_analyzer} ] }] }这与manifest.json中声明的cmd_out: tool_register与cmd_in: tool_call接口一一对应manifest.json。LLM 工具契约get_wellness_metrics 与状态机扩展注册了多个工具get_tool_metadata其中最核心的是get_wellness_metricsLLM 调用后返回如下 JSON{ status: available, metrics: { distress: 7.2, stress: 8.1, burnout: 6.5, fatigue: 5.8, low_self_esteem: 4.3 }, analyzed_seconds_ago: 12, speech_duration: 32.1 }README 中指标按 0~10 量表示例从源码看run_tool实际返回的是round(value * 100)的 0~100 整数百分比extension.py同时工具描述也明确要求 LLM 以百分比整数呈现给用户——接入时请以源码行为为准。在demo_dual模式下若 Apollo 分析完成响应中还会追加clinical_indicatorsdepression/anxiety 的概率百分比与 severity 等级若 Hellos 失败而 Apollo 成功则返回status: partial并只携带临床指标。状态值语义available指标已就绪可直接向用户播报analyzing分析进行中已触发 API 请求等待结果insufficient_data正在采集语音有效语音尚未达到门槛响应中会附带已采集/所需时长no_data尚未采集到任何语音error服务暂时不可用异常兜底返回。除此之外扩展还注册了三个配套工具confirm_announcementLLM 播报结果后回执确认带phase: hellos/apollo参数用于驱动系统的重试与完成追踪、check_phase_progressdemo_dual 模式下查询 mood/reading 阶段进度并顺带采集用户姓名、出生年份、性别、locale 供 Thymia API 使用、test_announcement_system验证 text_data 消息通道的测试工具。底层原理一AudioBuffer——带起止检测的智能语音缓冲AudioBufferextension.py是整条分析链路的起点核心逻辑包含三个层面1. RMS 音量判定。每个 10ms16kHz、单声道、16bit 320 字节PCM 帧被解包为 16-bit 整数计算均方根并除以 32768 归一化到 0~1与silence_threshold默认 0.02比较得到是否语音。2. 自然起点捕获pre-speech padding。未说话时最近的 0.5 秒音频被放入一个deque环形缓冲O(1) 的popleft()裁剪。一旦检测到语音起点环形缓冲中的前置音频会被拼进语音缓冲——这保证分析音频包含说话人开口前的环境上下文但前置填充不计入actual_speech_duration。3. 自然终点判定。说话期间若连续累积 0.5 秒静音则判定语句结束尾随静音不会被计入缓冲说话中途的短暂停顿则会作为语音的一部分保留。缓冲设有 300 秒5 分钟的容量上限防止内存无限增长。get_wav_data()会将缓冲的 PCM 拼合并附加 RIFF/WAVE 头pcm_to_wav手写 44 字节 WAV 头见 extension.py全程在内存中完成无磁盘 I/O。分析结束后clear_buffer()清空缓冲为下一轮持续监测腾出空间。底层原理二Thymia API 客户端——三段式异步工作流ThymiaAPIClientextension.py封装了 Hellos Mental Wellness API 的标准流程创建会话POST/v1/models/mental-wellness携带userLabel默认anonymous、dateOfBirth、birthSex、language默认en-GB源码注释说明该 locale 对 Thymia 语音检测效果更好响应返回session_id与预签名 S3recordingUploadUrl。该请求在源码中通过curl子进程异步执行并在日志中做 API Key 掩码只显示前 8 位与后 4 位。上传音频用 aiohttp 将内存中的 WAV 数据 PUT 到预签名 URLContent-Type: audio/wav成功状态码为 200/201/204。轮询结果以poll_interval默认 5s间隔 GET 会话状态直到返回COMPLETE_OK/COMPLETE_ERROR/FAILED或超过poll_timeout超时。结果从results.sections[0]中提取uniformDistress、uniformStress、uniformExhaustion、uniformSleepPropensity、uniformLowSelfEsteem五个字段。此外demo_dual模式还会启用ApolloAPIapollo_api.py它走另一套流程POST/v1/models/apollo创建 model run 拿到两份预签名 URL分别上传情绪问答与朗读两段 PCM 音频用_split_pcm_by_duration在apollo_mood_duration处切分再轮询获取depression/anxiety的概率0~1与严重等级NONE / MILD / MODERATE / SEVERE。Apollo 请求还会带上deleteData: true即处理完成后删除数据。后台调度统一轮询器、主动通知与优雅打断保护扩展在on_start时启动一个常驻的_unified_results_poller任务extension.py每 5 秒做四件事轮询 Hellos 会话直到完成成功后解析并缓存WellnessMetrics检查 Apollo 是否完成并待通知对未确认的通知做重试每 30 秒重发一次最多 3 次90 秒强制结束避免无限重试当用户沉默超过 15 秒且阶段未完成时向 LLM 发送[PROGRESS CHECK]提示引导 LLM 继续提问以补充语音样本。分析结果就绪后扩展通过text_data消息role: system、end_of_segment: true向 LLM 发送形如[SYSTEM ALERT] Wellness metrics ready. IMMEDIATELY call get_wellness_metrics...的主动通知。为了避免打扰正在进行的对话扩展监听tts_audio_start/tts_audio_end数据消息on_data精确计算 Agent 的 TTS 播放结束时间戳任何通知都只在用户与 Agent 都不说话的空档发送两次通知之间强制保持至少 15 秒间隔ANNOUNCEMENT_MIN_SPACING_SECONDS。这一整套机制保证了后台分析 前台不插话的体验。两种分析模式hellos_only 与 demo_dualhellos_only默认兼容模式只采集min_speech_duration默认 30s有效语音走 Hellos API 输出 5 项健康指标逻辑最简单适合快速接入。demo_dual采用两阶段采集——先 20~30 秒情绪问答语音再叠加 20~30 秒朗读语音总计约 40~60 秒Hellos 在 mood 阶段即可触发上传Apollo 在 reading 阶段完成后独立触发两条 API 流程并行、互不等待。最终 LLM 可以同时播报 5 项健康指标和 2 项临床指标其中临床指标在工具描述中被明确要求作为研究性指标而非临床诊断来呈现。两种模式通过analysis_mode属性切换仓库 property.json 默认采用demo_dual。依赖与运行环境扩展仅依赖aiohttprequirements.txtpyproject.toml声明aiohttp3.14.1、Python3.10并以ten_runtime_python0.11 为系统依赖manifest.json。运行前需确保在环境中导出THYMIA_API_KEY或直接在节点属性中配置明文api_key图配置中完成本文三步接入中的音频路由与工具注册LLM 侧正确理解get_wellness_metrics的返回值与状态机语义工具描述已内嵌完整使用指引LLM 会在收到[SYSTEM ALERT]时自动触发调用。隐私与安全注意事项默认使用anonymous用户标签dateOfBirth等缺失字段回退为占位默认值api_key必须显式配置否则扩展禁用音频会被发送至 Thymia 第三方 API属于跨服务数据传输生产部署需结合自身用例评估用户知情同意等合规要求日志中对 API Key 做了掩码处理避免密钥泄露到日志流Apollo 模式默认请求deleteData: true缩短第三方服务端的数据留存周期。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐TEN Framework Voice Assistant Advanced融合 Avatar 数字人与 Thymia 心理健康分析的 7 图语音助手实战指南TEN Framework Voice Assistant Advanced融合 Avatar 数字人与 Thymia 心理健康分析的 7 图语音助手实战指南人工智能AI Agent多模态语音AI 应用TEN Framework 语音活动检测实战webrtc_vad_cpp C 扩展详解TEN Framework 语音活动检测实战webrtc_vad_cpp C 扩展详解 TEN Framework 面向会话式语音 AI Agent 场景人工智能AI Agent多模态语音AI 应用TEN Framework Ollama Python 扩展实战异步 LLM 扩展示例与源码解析TEN Framework Ollama Python 扩展实战异步 LLM 扩展示例与源码解析 导读 ollama_python 是 TEN Framewo人工智能AI Agent多模态语音AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考