Tolan/backend/STT_DEBUG_GUIDE.md

STT 丢失前半句诊断指南 ✅ 已修复

✅ 问题已解决

根本原因

STT引擎使用 text（已确认文本） + stash（缓冲区文本）两部分返回识别结果。

旧代码问题：

# ❌ 只取 stash，丢失 text
text = response.get('stash', '')

修复方案：

# ✅ 合并 text + stash
confirmed_text = response.get('text', '')
stash_text = response.get('stash', '')
full_text = confirmed_text + stash_text

---

问题现象（修复前）

用户说：

您好，您好，今天星期几啊？今天天气晴朗吗？

STT识别（旧代码）：

今天星期几啊？  ❌ 前半句丢失

STT识别（修复后）：

您好，您好，今天星期几啊？今天天气晴朗吗？  ✅ 完整

---

技术细节：STT 的 text 和 stash 机制

实际日志示例（第418行）

{
    'event_id': 'event_NuDCx5B4dCYVpi7G5NysL',
    'type': 'conversation.item.input_audio_transcription.text',
    'content_index': 0,
    'text': '你好，你好，今天星期几啊？今天天气晴朗吗？',  ← 前面完整句子
    'stash': '今天星期几啊？'  ← 后面重复的话（当前缓冲区）
}

说明：

• 用户在 2.30秒 说完完整句子："您好，您好，今天星期几啊？今天天气晴朗吗？"
• 用户在 6.26秒 附近有停顿，然后继续说话（可能重复或纠正）
• STT引擎检测到停顿，将前面的内容放到 text（已确认），后面继续识别的放到 stash（缓冲区）

旧代码为什么丢失前半句

# ❌ 旧代码只取 stash
def _handle_stash_text(self, response):
    text = response.get('stash', '')  # 只取 '今天星期几啊？'
    # 丢失了 text 字段中的 '你好，你好，今天星期几啊？今天天气晴朗吗？'

修复后的完整逻辑

# ✅ 新代码合并 text + stash
def _handle_stash_text(self, response):
    confirmed_text = response.get('text', '')  # '你好，你好，今天星期几啊？今天天气晴朗吗？'
    stash_text = response.get('stash', '')     # '今天星期几啊？'
    full_text = confirmed_text + stash_text    # 合并完整文本

---

时间线分析（真实日志）

时间	事件	文本内容
2.30秒	中间结果	stash: "你好，你好，今天星期几啊？今天天气晴朗吗？" (21字 ✅)
6.26秒	开始断句	text: "你好" + stash: "，你好，今天星期"
6.35秒	继续拆分	text: "你好，你好，今天星期几啊？" + stash: "今天天气晴朗吗"
6.41秒	最终拆分	text: "你好，你好，今天星期几啊？今天天气晴朗吗？" + stash: "今天星期几啊？"
7.58秒	录音结束	调用 commit()
commit后	STT关闭	❌ 没有最终结果事件
超时	旧代码	只取 stash → "今天星期几啊？" (7字) ❌ 丢失前面21字！
超时	新代码	取 text + stash → "你好，你好，今天星期几啊？今天天气晴朗吗？今天星期几啊？" ✅ 完整！

---

🧪 验证修复

重启后端测试

cd /Users/wuzilong/work/00code/Tolan/backend
python main.py

期望的新日志格式

[xxx] 💬 STT识别(⏳中间): 您好，您好，今天星期几啊？今天天气晴朗吗？ (长度: 21字)
[xxx]    ├─ 已确认: 您好，您好，今天星期几啊？今天天气晴朗吗？ (21字)
[xxx]    └─ 缓冲区:  (0字)

（用户停顿后继续说话）

[xxx] 💬 STT识别(⏳中间): 您好，您好，今天星期几啊？今天天气晴朗吗？今天星期几啊？ (长度: 28字)
[xxx]    ├─ 已确认: 您好，您好，今天星期几啊？今天天气晴朗吗？ (21字)
[xxx]    └─ 缓冲区: 今天星期几啊？ (7字)

现在会看到完整的识别结果！ ✅

---

💡 额外优化建议

如果后续发现用户重复说话导致文本冗余，可以考虑：

方案1：去重处理

# 检测 stash 是否是 text 的子串（重复说话）
if stash_text in confirmed_text:
    full_text = confirmed_text  # 只用确认部分
else:
    full_text = confirmed_text + stash_text  # 合并

方案2：智能断句

• 检测句号、问号、感叹号
• 只在完整句子结束时更新

方案3：使用最终结果

• 当前主要依赖中间结果
• 可以优先等待 transcript（最终结果）