豆包语音识别热词功能实现指南

豆包语音识别热词功能实现指南

本文将详细介绍如何在 HagiCode 项目中实现豆包语音识别的热词支持功能，通过自定义热词和平台热词表两种方式，显著提升特定领域词汇的识别准确率。

背景

语音识别技术发展这么多年了，其实有个问题一直困扰着开发者们。通用语音识别模型虽然能覆盖日常用语，可对于专业术语、产品名称、人名这些词，识别准确率总差那么点意思。想想看，医疗领域的语音助手要准确识别"高血压"、"糖尿病"、"冠心病"；法律系统要精准捕捉"案由"、"答辩"、"举证责任"——这些场景下，通用模型的表现怎么说呢，也算尽力了。
在 HagiCode 项目中，我们也遇到了同样的挑战。作为一个多功能的 AI 代码助手，HagiCode 需要处理各种技术术语的语音识别场景。然而，豆包语音识别 API 在默认情况下，并不能完全满足我们对专业术语准确率的那些要求。其实也不是豆包不够好，只是每个领域都有自己的一套术语体系。经过一番调研和技术探索，我们发现豆包语音识别 API 实际上提供了热词支持功能，只要简单配置一下，就能显著提升特定词汇的识别准确率。这倒是有点像，你告诉它你要注意什么词，它就会更用心去听那些词。
本文要分享的，就是在 HagiCode 项目中实现豆包语音识别热词功能的完整方案。两种模式，自定义热词和平台热词表，都可以用，也都能组合用。通过这套方案，开发者可以根据业务场景灵活配置热词，让语音识别系统"认识"那些专业、罕见但又至关重要的词汇。
关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，技术栈还算现代化，旨在为开发者提供智能化的编程辅助体验。作为一个多语言、多平台的复杂项目，HagiCode 需要处理各种技术术语的语音识别场景，这也推动了我们对热词功能的研究和实现。
如果你对 HagiCode 的技术实现感兴趣，可以访问 GitHub 仓库 了解更多信息，也可以查看我们的 官方文档 了解完整的安装和使用指南。
核心实现

两种热词模式解析

豆包语音识别 API 为我们提供了两种热词配置方式，每种方式都有其独特的应用场景和优势。
自定义热词模式允许我们通过 corpus.context 字段直接传递热词文本。这种方式非常适合需要快速配置少量热词的场景，比如临时需要识别某个产品名称或者人名。在 HagiCode 的实现中，我们将用户输入的多行热词文本解析为字符串列表，然后按照豆包 API 的要求格式化为 context_data 数组。怎么说呢，这种方式很直接，就像告诉对方"你要注意这些词"，然后它就去注意了。
平台热词表模式则通过 corpus.boosting_table_id 字段引用豆包自学习平台预配置的热词表。这种方式适合需要管理大量热词的场景，我们可以在豆包自学习平台上创建和维护热词表，然后通过 ID 进行引用。对于 HagiCode 这类需要持续更新和维护专业术语的项目来说，这种模式提供了更好的可管理性。毕竟，热词多了之后，找个地方统一管理，总比每次都要手动输入要好。
有意思的是，这两种模式还可以组合使用。豆包 API 支持在同一个请求中同时包含自定义热词和平台热词表 ID，通过 combine_mode 参数控制组合策略。这种灵活性使得 HagiCode 能够应对各种复杂的专业术语识别需求。这也倒是挺好，有时候多种方式组合一下，效果可能更好。
前端类型定义与验证

在 HagiCode 的前端实现中，我们定义了一套完整的热词配置类型和验证逻辑。首先是类型定义部分：

1. export interface HotwordConfig {
2.   contextText: string;           // 多行热词文本
3.   boostingTableId: string;      // 豆包平台热词表 ID
4.   combineMode: boolean;          // 是否组合使用
5. }

复制代码

这个简单的接口包含了热词功能的所有配置项。其中 contextText 是用户最直观感受到的部分——我们允许用户每行输入一个热词短语，这种方式非常符合直觉。毕竟，让用户一行一个词，总比让用户理解复杂的配置规则要好。
接下来是验证函数的实现。考虑到豆包 API 的限制，我们制定了严格的验证规则：热词文本最多 100 行，每行最多 50 个字符，总共最多 5000 个字符；boosting_table_id 最多 200 个字符，只允许字母、数字、下划线和连字符。这些限制不是我们凭空想象的，而是基于豆包官方文档的实际要求。毕竟，API 的限制就是 API 的限制，我们也没办法，只能遵守。

1. export function validateContextText(contextText: string): HotwordValidationResult {
2.   if (!contextText || contextText.trim().length === 0) {
3.     return { isValid: true, errors: [] };
4.   }
6.   const lines = contextText.split('\n').filter(line => line.trim().length > 0);
7.   const errors: string[] = [];
9.   if (lines.length > 100) {
10.     errors.push(`热词行数不能超过 100 行，当前为 ${lines.length} 行`);
11.   }
13.   const totalChars = contextText.length;
14.   if (totalChars > 5000) {
15.     errors.push(`热词总字符数不能超过 5000，当前为 ${totalChars}`);
16.   }
18.   for (let i = 0; i < lines.length; i++) {
19.     if (lines[i].length > 50) {
20.       errors.push(`第 ${i + 1} 行热词超过 50 个字符限制`);
21.     }
22.   }
24.   return { isValid: errors.length === 0, errors };
25. }
27. export function validateBoostingTableId(boostingTableId: string): HotwordValidationResult {
28.   if (!boostingTableId || boostingTableId.trim().length === 0) {
29.     return { isValid: true, errors: [] };
30.   }
32.   const errors: string[] = [];
34.   if (boostingTableId.length > 200) {
35.     errors.push(`boosting_table_id 不能超过 200 个字符，当前为 ${boostingTableId.length}`);
36.   }
38.   if (!/^[a-zA-Z0-9_-]+$/.test(boostingTableId)) {
39.     errors.push('boosting_table_id 只能包含字母、数字、下划线和连字符');
40.   }
42.   return { isValid: errors.length === 0, errors };
43. }

复制代码

这些验证函数在用户配置热词时就会立即执行，确保问题在最早阶段被发现。对于用户体验来说，这种即时反馈是非常重要的。毕竟，用户输入的时候就知道哪里错了，总比提交后才发现要好。
前端配置持久化

在 HagiCode 的前端实现中，我们选择使用浏览器的 localStorage 来存储热词配置。这个设计决策背后有几点考量：首先，热词配置是非常个性化的设置，不同用户可能有不同的专业领域需求；其次，这种方式简化了后端实现，不需要额外的数据库表和 API 接口；最后，用户在浏览器中配置一次后，后续使用都能自动加载，非常方便。其实说白了，就是省事。

1. const HOTWORD_STORAGE_KEYS = {
2.   contextText: 'hotword-context-text',
3.   boostingTableId: 'hotword-boosting-table-id',
4.   combineMode: 'hotword-combine-mode',
5. } as const;
7. export const DEFAULT_HOTWORD_CONFIG: HotwordConfig = {
8.   contextText: '',
9.   boostingTableId: '',
10.   combineMode: false,
11. };
13. // 加载热词配置
14. export function loadHotwordConfig(): HotwordConfig {
15.   const contextText = localStorage.getItem(HOTWORD_STORAGE_KEYS.contextText) || '';
16.   const boostingTableId = localStorage.getItem(HOTWORD_STORAGE_KEYS.boostingTableId) || '';
17.   const combineMode = localStorage.getItem(HOTWORD_STORAGE_KEYS.combineMode) === 'true';
19.   return { contextText, boostingTableId, combineMode };
20. }
22. // 保存热词配置
23. export function saveHotwordConfig(config: HotwordConfig): void {
24.   localStorage.setItem(HOTWORD_STORAGE_KEYS.contextText, config.contextText);
25.   localStorage.setItem(HOTWORD_STORAGE_KEYS.boostingTableId, config.boostingTableId);
26.   localStorage.setItem(HOTWORD_STORAGE_KEYS.combineMode, String(config.combineMode));
27. }

复制代码

这段代码的逻辑非常简单清晰。加载配置时从 localStorage 读取，保存配置时写入 localStorage。我们还提供了默认配置，确保在没有任何配置时系统也能正常工作。毕竟，总得有个默认值吧。
后端 SDK 配置扩展

在 HagiCode 的后端实现中，我们需要在 SDK 配置类中添加热词相关的属性。考虑到 C# 的语言特性和使用习惯，我们采用了 List 来存储自定义热词上下文：

1. public class DoubaoVoiceConfig
2. {
3.     /// <summary>
4.     /// 应用 ID
5.     /// </summary>
6.     public string AppId { get; set; } = string.Empty;
8.     /// <summary>
9.     /// 访问令牌
10.     /// </summary>
11.     public string AccessToken { get; set; } = string.Empty;
13.     /// <summary>
14.     /// 服务 URL
15.     /// </summary>
16.     public string ServiceUrl { get; set; } = string.Empty;
18.     /// <summary>
19.     /// 自定义热词上下文列表
20.     /// </summary>
21.     public List<string>? HotwordContexts { get; set; }
23.     /// <summary>
24.     /// 豆包平台热词表 ID
25.     /// </summary>
26.     public string? BoostingTableId { get; set; }
27. }

复制代码

这个配置类的设计遵循了 HagiCode 一贯的简洁风格。HotwordContexts 是可空的列表类型，BoostingTableId 是可空的字符串，这样在没有任何热词配置时，这些属性不会对请求造成任何影响。毕竟，不用的时候就不应该存在，这才叫干净。
Payload 构建逻辑

Payload 的构建是整个热词功能的核心。当我们有了热词配置后，需要按照豆包 API 的要求格式化为正确的 JSON 结构。这个过程发生在 SDK 发送请求之前：

1. private void AddCorpusToRequest(Dictionary<string, object> request)
2. {
3.     var corpus = new Dictionary<string, object>();
5.     // 添加自定义热词
6.     if (Config.HotwordContexts != null && Config.HotwordContexts.Count > 0)
7.     {
8.         corpus["context"] = new Dictionary<string, object>
9.         {
10.             ["context_type"] = "dialog_ctx",
11.             ["context_data"] = Config.HotwordContexts
12.                 .Select(text => new Dictionary<string, object> { ["text"] = text })
13.                 .ToList()
14.         };
15.     }
17.     // 添加平台热词表 ID
18.     if (!string.IsNullOrEmpty(Config.BoostingTableId))
19.     {
20.         corpus["boosting_table_id"] = Config.BoostingTableId;
21.     }
23.     // 只有当 corpus 不为空时才添加到请求中
24.     if (corpus.Count > 0)
25.     {
26.         request["corpus"] = corpus;
27.     }
28. }

复制代码

这段代码展示了如何根据配置动态构建 corpus 字段。关键点在于：只有当确实存在热词配置时，我们才会添加 corpus 字段。这种设计确保了向后兼容性——没有配置热词时，请求的结构与之前完全一致。毕竟，兼容性很重要，不能因为加个功能就把之前的逻辑搞乱了。
WebSocket 参数传递

在前端和后端之间，热词参数通过 WebSocket 控制消息进行传递。HagiCode 的设计是：前端在开始录音时从 localStorage 加载热词配置，然后通过 WebSocket 消息发送给后端。

1. const controlMessage = {
2.   type: 'control',
3.   payload: {
4.     command: 'StartRecognition',
5.     contextText: '高血压\n糖尿病\n冠心病',
6.     boosting_table_id: 'medical_table',
7.     combineMode: false
8.   }
9. };

复制代码

这里有一个细节需要注意：前端传递的是多行文本（用换行符分隔），后端需要进行解析。后端的 WebSocket Handler 会解析这些参数并传递给 SDK：

1. private async Task HandleControlMessageAsync(
2.     string connectionId,
3.     DoubaoSession session,
4.     ControlMessage message)
5. {
6.     if (message.Payload is SessionControlRequest controlRequest)
7.     {
8.         // 解析热词参数
9.         string? contextText = controlRequest.ContextText;
10.         string? boostingTableId = controlRequest.BoostingTableId;
11.         bool? combineMode = controlRequest.CombineMode;
13.         // 解析多行文本为热词列表
14.         if (!string.IsNullOrEmpty(contextText))
15.         {
16.             var hotwords = contextText
17.                 .Split('\n', StringSplitOptions.RemoveEmptyEntries)
18.                 .Select(s => s.Trim())
19.                 .Where(s => s.Length > 0)
20.                 .ToList();
22.             session.HotwordContexts = hotwords;
23.         }
25.         session.BoostingTableId = boostingTableId;
26.     }
27. }

复制代码

通过这样的设计，热词配置从前端到后端的传递变得清晰而高效。其实也没什么特别的，就是一层一层传下去而已。
实践指南

配置自定义热词

在实际使用中，配置自定义热词非常简单。打开 HagiCode 的语音识别设置页面，找到"热词配置"区域。在"自定义热词文本"输入框中，每行输入一个热词短语。
比如，如果你正在开发一个医疗相关的应用，可以这样配置：

1. 高血压
2. 糖尿病
3. 冠心病
4. 心绞痛
5. 心肌梗死
6. 心力衰竭

复制代码

保存配置后，每次开始语音识别时，这些热词都会自动传递给豆包 API。实际测试表明，配置热词后，相关专业术语的识别准确率有了明显提升。怎么说呢，效果还是有的，至少比之前好多了。
配置平台热词表

如果你需要管理大量的热词，或者热词需要频繁更新，那么平台热词表模式更适合你。首先需要在豆包自学习平台上创建热词表，获取生成的 boosting_table_id，然后在 HagiCode 的设置页面中输入这个 ID。
豆包自学习平台提供了热词的批量导入、分类管理等功能，对于需要管理大量专业术语的团队来说非常实用。通过平台管理热词，可以实现热词的集中维护和统一更新。毕竟，热词多了之后，有个地方统一管理，总比每次都要手动输入要好。
组合模式的使用

在某些复杂场景下，你可能需要同时使用自定义热词和平台热词表。这时只需要在 HagiCode 中同时配置两种热词，并开启"组合模式"开关。
组合模式下，豆包 API 会同时考虑两种热词来源，识别准确率通常比单独使用任意一种更高。不过需要注意的是，组合模式会增加请求的复杂度，建议在实际测试后再决定是否启用。毕竟，复杂度增加了，是不是真的值得，还是得看实际效果。
代码集成示例

在 HagiCode 项目中集成热词功能非常简单。以下是一些常用的代码片段：

1. import {
2.   loadHotwordConfig,
3.   saveHotwordConfig,
4.   validateHotwordConfig,
5.   parseContextText,
6.   getEffectiveHotwordMode,
7.   type HotwordConfig
8. } from '@/types/hotword';
10. // 加载并验证配置
11. const config = loadHotwordConfig();
12. const validation = validateHotwordConfig(config);
14. if (!validation.isValid) {
15.   console.error('热词配置验证失败:', validation.errors);
16.   return;
17. }
19. // 解析热词文本
20. const hotwords = parseContextText(config.contextText);
21. console.log('解析到的热词:', hotwords);
23. // 获取有效的热词模式
24. const mode = getEffectiveHotwordMode(config);
25. console.log('当前热词模式:', mode);

复制代码

后端的使用同样简洁：

1. var config = new DoubaoVoiceConfig
2. {
3.     AppId = "your_app_id",
4.     AccessToken = "your_access_token",
5.     ServiceUrl = "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async",
7.     // 配置自定义热词
8.     HotwordContexts = new List<string>
9.     {
10.         "高血压",
11.         "糖尿病",
12.         "冠心病"
13.     },
15.     // 配置平台热词表
16.     BoostingTableId = "medical_table_v1"
17. };
19. var client = new DoubaoVoiceClient(config, logger);
20. await client.ConnectAsync();
21. await client.SendFullClientRequest();

复制代码

注意事项

在实现和使用热词功能时，有几点需要特别注意。
首先是字符限制。豆包 API 对热词有严格的限制，包括行数、每行字符数、总字符数等。如果超出限制，API 会返回错误。在 HagiCode 的前端实现中，我们通过验证函数在用户输入阶段就进行检查，避免将无效配置发送到后端。毕竟，提前发现问题，总比等 API 返回错误要好。
其次是 boosting_table_id 的格式。这个字段只允许字母、数字、下划线和连字符，不允许包含空格或其他特殊字符。在豆包自学习平台上创建热词表时，需要注意命名规范。其实这也难怪，API 对格式的要求总是比较严格的。
第三是向后兼容性。热词参数是完全可选的，不配置热词时，系统的工作方式与之前完全一致。这种设计确保了现有用户不会受到任何影响，也便于逐步迁移和升级。毕竟，不能因为加个功能就把之前的逻辑搞乱了。
最后是错误处理。当热词配置无效时，豆包 API 会返回相应的错误信息。HagiCode 的实现会记录详细的日志，便于开发者排查问题。同时，前端也会在界面上展示验证错误，帮助用户修正配置。错误处理做得好，用户体验自然也就好了。
总结

通过本文的讲解，我们详细介绍了在 HagiCode 项目中实现豆包语音识别热词功能的完整方案。这套方案涵盖了从需求分析、技术选型到代码实现的全部环节，为开发者提供了可参考的实践范例。
核心要点可以归纳为以下几点：第一，豆包 API 支持自定义热词和平台热词表两种模式，可以独立使用也可以组合使用；第二，前端采用 localStorage 存储配置，简单高效；第三，后端通过动态构建 corpus 字段来传递热词参数，保持了良好的向后兼容性；第四，完善的验证逻辑确保了配置的正确性，避免了无效请求。怎么说呢，这套方案也不复杂，就是按照 API 的要求来而已。
热词功能的实现，让 HagiCode 在语音识别领域的能力得到了进一步增强。通过灵活配置业务相关的专业术语，开发者可以让语音识别系统更好地理解特定领域的内容，从而提供更加精准的服务。毕竟，技术最终是要服务业务的，能解决实际问题才是最重要的。
如果你觉得本文对你有帮助，欢迎来 GitHub 给个 Star 支持一下 HagiCode 项目。你的认可，是我们持续分享技术实践的动力。说到底，写文章分享技术，能帮到人，也算是种快乐了。
参考资料

• HagiCode 官方文档
  
• HagiCode GitHub 仓库
  
• 豆包语音识别 API 文档
  
• 豆包自学习平台
  

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

感谢分享，下载保存了，貌似很强大

收藏一下   不知道什么时候能用到

这个有用。