企业官网建设流程全解析

Home Assistant TTS 缓存管理实战：tts.clear_cache 动作与缓存机制详解

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本文以 Home Assistant 官方文档中的tts.clear_cache动作为核心，讲解如何在自动化和脚本中清除全部已缓存的文本转语音（Text-to-Speech，TTS）文件与内存缓存，并结合 TTS 构建块的集成文档说明缓存的双层结构（文件系统长期缓存 + 内存缓存）、speak/say动作的cache选项与 REST API 之间的关系。读完后你将能够：在 UI 与 YAML 两种模式下正确使用该动作、判断“何时该清缓存、何时只需关闭缓存写入”，并理解 TTS 生成文件的存储与引用方式。

动作定位：tts.clear_cache 是做什么的

tts.clear_cache属于tts域（domain）的自动化动作，官方定义为：移除所有已缓存的文本转语音文件并清空内存缓存（Removes all cached text-to-speech files and clears the memory）。

文档给出的使用场景是：当你想释放磁盘空间，或强制让播报消息重新生成时使用。典型情况包括：

• TTS 消息数量多、语料变化大，长期缓存文件占用了过多磁盘空间；
• 更换了语音提供方（TTS 引擎/平台）、语音、音频格式等配置后，希望丢弃旧的合成结果，下次播报时使用新配置重新生成；
• 排查播报内容“对不上”的问题，排除旧缓存文件的影响。

该动作与 TTS 域的两个核心播报动作tts.speak（基于实体，UI 配置）和tts.say（基于 YAML 的遗留平台）互为关联动作，三者共同构成 TTS 构建块的完整操作面。

从用户界面（UI）使用该动作

对于偏好可视化编排的自动化与脚本，可以在编辑器中逐步完成。按文档给出的步骤操作：

1. 进入Settings > Automations & scenes（设置 > 自动化与场景）。
2. 打开一个已有的自动化或脚本，或选择Create automation > Create new automation创建新的自动化。
3. 如果是新建自动化，需要在When（触发条件）部分添加触发器；脚本不需要触发器，它由其他东西调用时运行。
4. 在Then do（执行动作）部分，选择Add action。
5. 搜索并选择Clear TTS cache。
6. 选择Save保存。

UI 中的可选项：无。该动作不接收任何参数，界面只提供一个开关式入口，选中即执行“清空全部 TTS 缓存”。

在 YAML 中使用该动作

在 YAML 中，该动作写作tts.clear_cache，同样不接受任何选项（options）。文档给出的最小示例是：

action: action: tts.clear_cache

嵌入到自动化或脚本的actions列表中时，一般写成：

- action: tts.clear_cache

由于没有任何参数，这个动作语句就是完整的——不需要target，也不存在data字段。这一点与tts.speak等需要指定实体、媒体播放器与消息文本的动作形成对比。

深入理解 TTS 缓存：为什么要“清”

要真正用好tts.clear_cache，需要先理解它清理的是什么。结合 TTS 集成文档（Cache 章节）与两个播报动作的文档，TTS 构建块的缓存由两层构成：

1. 文件系统上的长期缓存：合成好的音频文件会落在磁盘上，同一文本再次请求时可直接复用，避免重复调用语音引擎。
2. 内存缓存：用于对媒体播放器快速响应，会在较短时间内被自动清理。

文档原文说明：缓存可以通过speak或say动作的cache选项控制，置为True启用（默认），False禁用；“长期缓存位于文件系统上（A long time cache will be located on the file system）”，“内存缓存用于对媒体播放器的快速响应，会在短时间后自动清理（The in-memory cache for fast responses to media players will be auto-cleaned after a short period）”。

由此可以推断出两个关键区别：

• cache: false（写入侧）只控制“这一条消息是否写入缓存”，并不会清除已有的缓存内容；
• tts.clear_cache（清理侧）是“全量清空”：既删除磁盘上已缓存的全部 TTS 文件，也清空内存缓存。两者作用方向不同，不能互相替代。

另外，两个播报动作的cache选项默认值并不一致，使用时需注意（依据各自动作文档的 YAML 选项表）：

也就是说，通过 UI 配置、走tts.speak的播报默认会持续累积磁盘缓存，这正是tts.clear_cache最常见的清理对象；而遗留平台的say动作默认不写缓存，磁盘占用压力相对较小。

缓存文件如何被生成与引用：REST API 视角

TTS 集成文档还描述了 REST API 层面的缓存行为，可以佐证缓存文件的组织方式。POST /api/tts_get_url接口接收engine_id（即 TTS 实体 id）或platform参数加上message，同时支持cache、language、options等 JSON 属性（与speak动作的说明一致）。文件生成成功时返回 200，响应体中带一个指向生成文件的 URL：

{ "path": "/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3", "url": "http://127.0.0.1:8123/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3" }

从该返回结构可以看出：缓存文件以消息内容与引擎相关的哈希值命名（如示例中的265944c108cbb00b...），通过/api/tts_proxy/路径对外代理访问。这意味着同一文本 + 同一引擎会命中同一个缓存文件；当语音引擎、语言等影响生成结果的参数变化后，旧文件不会再被命中，但会一直留在磁盘上——这正是需要定期或手动执行tts.clear_cache的现实原因之一。

对应的curl示例（文档原文）：

$ curl -X POST -H "Authorization: Bearer <ACCESS TOKEN>" \ -H "Content-Type: application/json" \ -d '{"message": "I am speaking now", "engine_id": "amazon_polly"}' \ http://localhost:8123/api/tts_get_url

典型使用场景与组合思路

基于以上机制，给出几个文档支持范围内的实践组合（均为“查看/配置”性质，不涉及修改仓库）：

1. 定期释放空间：在脚本中放置- action: tts.clear_cache，例如配合每月定时触发器执行一次，防止长期使用tts.speak（默认cache: true）导致的缓存堆积。
2. 更换语音配置后强制重合成：修改 TTS 集成配置、切换语音或调整options（如preferred_format、preferred_sample_rate等首选音频设置，见 TTS 集成文档的 Preferred audio settings 章节）后，调用tts.clear_cache，下次播报即按新配置重新生成，避免新旧格式文件混杂。
3. 精确控制单条消息的缓存：若只是不想让某条特定消息写入缓存（而不是清空全部缓存），应在speak/say的data中设置cache: false，而非调用清理动作。
4. 排查播报内容异常：先执行tts.clear_cache再触发一次播报，可确认问题是否源于过期的缓存文件；若清缓存后恢复正常，说明是旧缓存命中所致。

注意文档在 “Good to know” 中强调的语义：清空缓存会同时移除磁盘文件与内存缓存，下次消息播报时会重新生成（The next time a message is spoken, it is generated again）。

要点速查

适用前提与限制：该动作面向的是 Home Assistant 的 TTS 构建块缓存，前提是你已配置至少一个 TTS 平台（tts.speak要求存在 TTS 实体，tts.say要求存在通过 YAML 配置的遗留平台）。执行后不会删除任何集成配置，只是丢弃已合成的音频产物；同时，媒体播放器播放 TTS 时优先使用本地 Home Assistant URL，缓存文件的可访问性依赖本地网络 URL 配置（TTS 集成文档的 Troubleshooting 章节有详细说明），清理缓存本身不影响 URL 配置。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io