WebSocket

2 posts with the tag “WebSocket”

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

Mar 6, 2026

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

本文将详细介绍如何在 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 的前端实现中，我们定义了一套完整的热词配置类型和验证逻辑。首先是类型定义部分：

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

这个简单的接口包含了热词功能的所有配置项。其中 contextText 是用户最直观感受到的部分——我们允许用户每行输入一个热词短语，这种方式非常符合直觉。毕竟，让用户一行一个词，总比让用户理解复杂的配置规则要好。

接下来是验证函数的实现。考虑到豆包 API 的限制，我们制定了严格的验证规则：热词文本最多 100 行，每行最多 50 个字符，总共最多 5000 个字符；boosting_table_id 最多 200 个字符，只允许字母、数字、下划线和连字符。这些限制不是我们凭空想象的，而是基于豆包官方文档的实际要求。毕竟，API 的限制就是 API 的限制，我们也没办法，只能遵守。

export function validateContextText(contextText: string): HotwordValidationResult {
  if (!contextText || contextText.trim().length === 0) {
    return { isValid: true, errors: [] };
  }

  const lines = contextText.split('\n').filter(line => line.trim().length > 0);
  const errors: string[] = [];

  if (lines.length > 100) {
    errors.push(`热词行数不能超过 100 行，当前为 ${lines.length} 行`);
  }

  const totalChars = contextText.length;
  if (totalChars > 5000) {
    errors.push(`热词总字符数不能超过 5000，当前为 ${totalChars}`);
  }

  for (let i = 0; i < lines.length; i++) {
    if (lines[i].length > 50) {
      errors.push(`第 ${i + 1} 行热词超过 50 个字符限制`);
    }
  }

  return { isValid: errors.length === 0, errors };
}

export function validateBoostingTableId(boostingTableId: string): HotwordValidationResult {
  if (!boostingTableId || boostingTableId.trim().length === 0) {
    return { isValid: true, errors: [] };
  }

  const errors: string[] = [];

  if (boostingTableId.length > 200) {
    errors.push(`boosting_table_id 不能超过 200 个字符，当前为 ${boostingTableId.length}`);
  }

  if (!/^[a-zA-Z0-9_-]+$/.test(boostingTableId)) {
    errors.push('boosting_table_id 只能包含字母、数字、下划线和连字符');
  }

  return { isValid: errors.length === 0, errors };
}

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

前端配置持久化

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

const HOTWORD_STORAGE_KEYS = {
  contextText: 'hotword-context-text',
  boostingTableId: 'hotword-boosting-table-id',
  combineMode: 'hotword-combine-mode',
} as const;

export const DEFAULT_HOTWORD_CONFIG: HotwordConfig = {
  contextText: '',
  boostingTableId: '',
  combineMode: false,
};

// 加载热词配置
export function loadHotwordConfig(): HotwordConfig {
  const contextText = localStorage.getItem(HOTWORD_STORAGE_KEYS.contextText) || '';
  const boostingTableId = localStorage.getItem(HOTWORD_STORAGE_KEYS.boostingTableId) || '';
  const combineMode = localStorage.getItem(HOTWORD_STORAGE_KEYS.combineMode) === 'true';

  return { contextText, boostingTableId, combineMode };
}

// 保存热词配置
export function saveHotwordConfig(config: HotwordConfig): void {
  localStorage.setItem(HOTWORD_STORAGE_KEYS.contextText, config.contextText);
  localStorage.setItem(HOTWORD_STORAGE_KEYS.boostingTableId, config.boostingTableId);
  localStorage.setItem(HOTWORD_STORAGE_KEYS.combineMode, String(config.combineMode));
}

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

后端 SDK 配置扩展

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

public class DoubaoVoiceConfig
{
    /// <summary>
    /// 应用 ID
    /// </summary>
    public string AppId { get; set; } = string.Empty;

    /// <summary>
    /// 访问令牌
    /// </summary>
    public string AccessToken { get; set; } = string.Empty;

    /// <summary>
    /// 服务 URL
    /// </summary>
    public string ServiceUrl { get; set; } = string.Empty;

    /// <summary>
    /// 自定义热词上下文列表
    /// </summary>
    public List<string>? HotwordContexts { get; set; }

    /// <summary>
    /// 豆包平台热词表 ID
    /// </summary>
    public string? BoostingTableId { get; set; }
}

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

Payload 构建逻辑

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

private void AddCorpusToRequest(Dictionary<string, object> request)
{
    var corpus = new Dictionary<string, object>();

    // 添加自定义热词
    if (Config.HotwordContexts != null && Config.HotwordContexts.Count > 0)
    {
        corpus["context"] = new Dictionary<string, object>
        {
            ["context_type"] = "dialog_ctx",
            ["context_data"] = Config.HotwordContexts
                .Select(text => new Dictionary<string, object> { ["text"] = text })
                .ToList()
        };
    }

    // 添加平台热词表 ID
    if (!string.IsNullOrEmpty(Config.BoostingTableId))
    {
        corpus["boosting_table_id"] = Config.BoostingTableId;
    }

    // 只有当 corpus 不为空时才添加到请求中
    if (corpus.Count > 0)
    {
        request["corpus"] = corpus;
    }
}

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

WebSocket 参数传递

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

const controlMessage = {
  type: 'control',
  payload: {
    command: 'StartRecognition',
    contextText: '高血压\n糖尿病\n冠心病',
    boosting_table_id: 'medical_table',
    combineMode: false
  }
};

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

private async Task HandleControlMessageAsync(
    string connectionId,
    DoubaoSession session,
    ControlMessage message)
{
    if (message.Payload is SessionControlRequest controlRequest)
    {
        // 解析热词参数
        string? contextText = controlRequest.ContextText;
        string? boostingTableId = controlRequest.BoostingTableId;
        bool? combineMode = controlRequest.CombineMode;

        // 解析多行文本为热词列表
        if (!string.IsNullOrEmpty(contextText))
        {
            var hotwords = contextText
                .Split('\n', StringSplitOptions.RemoveEmptyEntries)
                .Select(s => s.Trim())
                .Where(s => s.Length > 0)
                .ToList();

            session.HotwordContexts = hotwords;
        }

        session.BoostingTableId = boostingTableId;
    }
}

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

实践指南

配置自定义热词

在实际使用中，配置自定义热词非常简单。打开 HagiCode 的语音识别设置页面，找到”热词配置”区域。在”自定义热词文本”输入框中，每行输入一个热词短语。

比如，如果你正在开发一个医疗相关的应用，可以这样配置：

高血压
糖尿病
冠心病
心绞痛
心肌梗死
心力衰竭

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

配置平台热词表

如果你需要管理大量的热词，或者热词需要频繁更新，那么平台热词表模式更适合你。首先需要在豆包自学习平台上创建热词表，获取生成的 boosting_table_id，然后在 HagiCode 的设置页面中输入这个 ID。

豆包自学习平台提供了热词的批量导入、分类管理等功能，对于需要管理大量专业术语的团队来说非常实用。通过平台管理热词，可以实现热词的集中维护和统一更新。毕竟，热词多了之后，有个地方统一管理，总比每次都要手动输入要好。

组合模式的使用

在某些复杂场景下，你可能需要同时使用自定义热词和平台热词表。这时只需要在 HagiCode 中同时配置两种热词，并开启”组合模式”开关。

组合模式下，豆包 API 会同时考虑两种热词来源，识别准确率通常比单独使用任意一种更高。不过需要注意的是，组合模式会增加请求的复杂度，建议在实际测试后再决定是否启用。毕竟，复杂度增加了，是不是真的值得，还是得看实际效果。

代码集成示例

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

import {
  loadHotwordConfig,
  saveHotwordConfig,
  validateHotwordConfig,
  parseContextText,
  getEffectiveHotwordMode,
  type HotwordConfig
} from '@/types/hotword';

// 加载并验证配置
const config = loadHotwordConfig();
const validation = validateHotwordConfig(config);

if (!validation.isValid) {
  console.error('热词配置验证失败:', validation.errors);
  return;
}

// 解析热词文本
const hotwords = parseContextText(config.contextText);
console.log('解析到的热词:', hotwords);

// 获取有效的热词模式
const mode = getEffectiveHotwordMode(config);
console.log('当前热词模式:', mode);

后端的使用同样简洁：

var config = new DoubaoVoiceConfig
{
    AppId = "your_app_id",
    AccessToken = "your_access_token",
    ServiceUrl = "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async",

    // 配置自定义热词
    HotwordContexts = new List<string>
    {
        "高血压",
        "糖尿病",
        "冠心病"
    },

    // 配置平台热词表
    BoostingTableId = "medical_table_v1"
};

var client = new DoubaoVoiceClient(config, logger);
await client.ConnectAsync();
await client.SendFullClientRequest();

注意事项

在实现和使用热词功能时，有几点需要特别注意。

首先是字符限制。豆包 API 对热词有严格的限制，包括行数、每行字符数、总字符数等。如果超出限制，API 会返回错误。在 HagiCode 的前端实现中，我们通过验证函数在用户输入阶段就进行检查，避免将无效配置发送到后端。毕竟，提前发现问题，总比等 API 返回错误要好。

其次是 boosting_table_id 的格式。这个字段只允许字母、数字、下划线和连字符，不允许包含空格或其他特殊字符。在豆包自学习平台上创建热词表时，需要注意命名规范。其实这也难怪，API 对格式的要求总是比较严格的。

第三是向后兼容性。热词参数是完全可选的，不配置热词时，系统的工作方式与之前完全一致。这种设计确保了现有用户不会受到任何影响，也便于逐步迁移和升级。毕竟，不能因为加个功能就把之前的逻辑搞乱了。

最后是错误处理。当热词配置无效时，豆包 API 会返回相应的错误信息。HagiCode 的实现会记录详细的日志，便于开发者排查问题。同时，前端也会在界面上展示验证错误，帮助用户修正配置。错误处理做得好，用户体验自然也就好了。

总结

通过本文的讲解，我们详细介绍了在 HagiCode 项目中实现豆包语音识别热词功能的完整方案。这套方案涵盖了从需求分析、技术选型到代码实现的全部环节，为开发者提供了可参考的实践范例。

核心要点可以归纳为以下几点：第一，豆包 API 支持自定义热词和平台热词表两种模式，可以独立使用也可以组合使用；第二，前端采用 localStorage 存储配置，简单高效；第三，后端通过动态构建 corpus 字段来传递热词参数，保持了良好的向后兼容性；第四，完善的验证逻辑确保了配置的正确性，避免了无效请求。怎么说呢，这套方案也不复杂，就是按照 API 的要求来而已。

热词功能的实现，让 HagiCode 在语音识别领域的能力得到了进一步增强。通过灵活配置业务相关的专业术语，开发者可以让语音识别系统更好地理解特定领域的内容，从而提供更加精准的服务。毕竟，技术最终是要服务业务的，能解决实际问题才是最重要的。

如果你觉得本文对你有帮助，欢迎来 GitHub 给个 Star 支持一下 HagiCode 项目。你的认可，是我们持续分享技术实践的动力。说到底，写文章分享技术，能帮到人，也算是种快乐了。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-06-doubao-speech-recognition-hotword-support/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。版权所有!

解决浏览器 WebSocket 认证难题：豆包语音识别的代理方案实践

Mar 5, 2026

解决浏览器 WebSocket 认证难题：豆包语音识别的代理方案实践

浏览器 WebSocket API 不支持自定义 HTTP header，这给需要通过 header 传递认证信息的语音识别服务带来了挑战。本文分享 HagiCode 项目中如何通过后端代理方案解决这个问题，以及从 playground 到生产环境的实践过程。

背景

其实在做 HagiCode 项目的语音识别功能时，我们也是满怀信心地选择了字节跳动的豆包语音识别服务。刚开始的设计很简单嘛——前端直接连豆包的 WebSocket 服务。这有什么难的？不就是建个连接，传点数据的事儿吗？

可是吧，万万没想到——豆包的 API 要求通过 HTTP header 传递认证信息，什么 accessToken、secretKey 之类的。这下就有点尴尬了，因为浏览器的 WebSocket API 根本不支持设置自定义 header。

你说不支持怎么办嘛？

那时候也是纠结了一阵子的。毕竟摆在面前的两个选择：

把认证信息塞到 URL 查询参数里——简单粗暴
在后端做一层代理——看起来麻烦一点

第一种方案吧，凭证就直接暴露在前端代码和本地存储里了。这安全吗？反正我是不太敢苟同的。而且有些 API 必须用 header 验证，根本走不通。

最终想了想，还是选了第二种方案——在后端实现一个 WebSocket 代理。说起来也是巧合，这个方案最初是在我们的 playground 试验场里验证的，后来确认稳定了才应用到生产环境。毕竟谁也不想在生产环境当小白鼠嘛，这点儿道理我还是懂的。

关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。

HagiCode 是一个 AI 代码助手项目，支持语音交互功能。怎么说呢，也就是因为需要在前端调用语音识别服务，我们才遇到了这个 WebSocket 认证问题，也才有了后面的解决方案。有时候想想吧，困难这东西也不是完全没有好处，至少让我们学会了用代理，不是吗？

技术挑战分析

浏览器 WebSocket 的限制

标准 WebSocket API 看起来真的很简单：

const ws = new WebSocket('wss://example.com/ws');

但问题就出在”简单”这两个字上——它只在 URL 里传递参数，没法像 HTTP 请求那样设置 headers：

// 这在 WebSocket API 里是不支持的
const ws = new WebSocket('wss://example.com/ws', {
  headers: {
    'Authorization': 'Bearer token'
  }
});

你看看，这找谁说理去？对于豆包语音识别这类需要 header 认证的服务，这个限制简直就是一道迈不过去的坎儿。

罢了罢了，又能怎样呢？

架构设计决策

在设计方案的时候，我们也是左思右想，权衡了又权衡。

决策一：代理模式选择

我们比较了两种方案：

方案	优点	缺点	决策
原生 WebSocket	轻量、简单、直接转发	需手动处理连接管理	选择
SignalR	自动重连、强类型	过度复杂、额外依赖	不选

最后选了原生 WebSocket。说实话，也就是因为它最轻量，适合简单的双向二进制流转发。加个 SignalR 吧，确实有点杀鸡用牛刀的感觉，而且会增加延迟——这又何苦呢？

决策二：连接管理策略

我们采用了”每连接单会话”模式——每个前端 WebSocket 连接对应一个独立的豆包后端连接。

这样做的好处也是显而易见的：

实现简单，符合典型使用场景
易于调试和故障排查
资源隔离，避免会话间互相干扰

其实说白了也就是——简单粗暴有时候反而是最好的选择。复杂的方案不一定好，简单的不一定差。

决策三：认证信息存储

凭证存在后端配置文件（appsettings.yml 或环境变量）里，通过依赖注入加载：

配置方式简单，符合现有后端配置模式
敏感信息不暴露给前端
支持多环境配置（开发、测试、生产）

这安全感嘛，总归是要有的。毕竟谁也不想自己的凭证满天飞，不是吗？

数据流设计

整体数据流是这样的：

前端 (浏览器)
  │
  │ ws://backend/api/voice/ws
  │ WebSocket (二进制)
  ▼
后端 (代理)
  │
  │ wss://openspeech.bytedance.com/
  │ (带认证 header)
  ▼
豆包 API

流程倒也不复杂，也就是这么几步：

前端通过 WebSocket 连接后端代理
后端代理接收音频数据，用带 header 的方式连接豆包 API
豆包 API 返回识别结果，代理转发给前端
全程异步双向流式传输

一切看起来都是那么自然，不是吗？

核心组件实现

1. WebSocket 端点配置

app.Map("/ws", async context =>
{
    if (context.WebSockets.IsWebSocketRequest)
    {
        // 从查询参数读取配置
        var appId = context.Request.Query["appId"];
        var accessToken = context.Request.Query["accessToken"];

        // 验证必需参数
        if (string.IsNullOrEmpty(appId) || string.IsNullOrEmpty(accessToken))
        {
            context.Response.StatusCode = 400;
            return;
        }

        // 接受 WebSocket 连接
        using var webSocket = await context.WebSockets.AcceptWebSocketAsync();

        // 消息处理循环
        var buffer = new byte[4096];
        while (!webSocket.CloseStatus.HasValue)
        {
            var result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);

            if (result.MessageType == WebSocketMessageType.Close)
            {
                await webSocket.CloseAsync(
                    result.CloseStatus.Value,
                    result.CloseStatusDescription,
                    CancellationToken.None);
                break;
            }

            // 处理音频数据
            await HandleAudioDataAsync(buffer, result.Count);
        }
    }
});

2. 会话管理

public class DoubaoSessionManager : IDoubaoSessionManager
{
    private readonly ConcurrentDictionary<string, DoubaoSession> _sessions = new();

    public DoubaoSession CreateSession(string connectionId)
    {
        var session = new DoubaoSession(connectionId);
        _sessions[connectionId] = session;
        return session;
    }

    public async Task SendAudioAsync(string connectionId, byte[] audioData)
    {
        if (_sessions.TryGetValue(connectionId, out var session))
        {
            await session.SendAudioAsync(audioData);
        }
    }

    public void RemoveSession(string connectionId)
    {
        if (_sessions.TryRemove(connectionId, out var session))
        {
            session.Dispose();
        }
    }
}

用 ConcurrentDictionary 管理会话，线程安全也就不用操心了。每个连接进来就创建一个 Session，断开时自动清理——这大概就是所谓的”来也匆匆，去也匆匆”罢。

3. 配置验证

public class ClientConfigDto
{
    public string AppId { get; set; } = null!;
    public string Access set; } =Token { get; null!;
    public string? ServiceUrl { get; set; }
    public string? ResourceId { get; set; }
    public int? SampleRate { get; set; }
    public int? BitsPerSample { get; set; }
    public int? Channels { get; set; }

    public void Validate()
    {
        if (string.IsNullOrWhiteSpace(AppId))
            throw new ArgumentException("AppId is required");
        if (string.IsNullOrWhiteSpace(AccessToken))
            throw new ArgumentException("AccessToken is required");
    }
}

配置验证嘛，也就是为了在启动时就发现问题，避免运行时出什么幺蛾子。这点儿保障还是要的。

消息协议设计

前端和后端之间用 JSON 格式的文本消息做控制，用二进制消息传音频数据。

控制消息示例：

{
    "type": "control",
    "messageId": "msg_123",
    "timestamp": "2026-03-03T10:00:00Z",
    "payload": {
        "command": "StartRecognition",
        "parameters": {
            "hotwordId": "hotword1",
            "boosting_table_id": "table123"
        }
    }
}

识别结果示例：

{
    "type": "result",
    "timestamp": "2026-03-03T10:00:03Z",
    "payload": {
        "text": "你好世界",
        "confidence": 0.95,
        "duration": 1500,
        "isFinal": true,
        "utterances": [
            {
                "text": "你好",
                "startTime": 0,
                "endTime": 800,
                "definite": true
            }
        ]
    }
}

这种设计把控制信号和音频数据分开，处理起来也是更清晰一些。有时候分而治之确实是个不错的办法。

前端接入实践

WebSocket 连接

class DoubaoVoiceClient {
    constructor(config) {
        this.config = config;
        this.ws = null;
    }

    async connect() {
        const url = new URL(this.config.wsUrl);
        // 添加查询参数
        Object.entries(this.config.params).forEach(([key, value]) => {
            url.searchParams.set(key, value);
        });

        this.ws = new WebSocket(url);

        return new Promise((resolve, reject) => {
            this.ws.onopen = () => {
                console.log('[DoubaoVoice] Connected');
                resolve();
            };

            this.ws.onmessage = (event) => {
                this._handleMessage(JSON.parse(event.data));
            };

            this.ws.onerror = reject;
        });
    }

    _handleMessage(message) {
        switch (message.type) {
            case 'status':
                this._handleStatus(message.payload);
                break;
            case 'result':
                this.onResult?.(message.payload);
                break;
            case 'error':
                console.error('[DoubaoVoice] Error:', message.payload);
                break;
        }
    }
}

// 使用示例
const client = new DoubaoVoiceClient({
    wsUrl: 'ws://localhost:5000/ws',
    params: {
        appId: 'your-app-id',
        accessToken: 'your-access-token',
        sampleRate: 16000,
        bitsPerSample: 16,
        channels: 1
    }
});

音频采集与发送

用 AudioWorkletNode 做音频处理，性能也会更好一些：

class AudioProcessorWorklet extends AudioWorkletProcessor {
    process(inputs, outputs, parameters) {
        const input = inputs[0]?.[0];
        if (!input) return true;

        // 转换为 16-bit PCM
        const pcm = new Int16Array(input.length);
        for (let i = 0; i < input.length; i++) {
            pcm[i] = Math.max(-32768, Math.min(32767, input[i] * 32767));
        }

        this.port.postMessage({
            type: 'audioData',
            data: pcm.buffer
        }, [pcm.buffer]);

        return true;
    }
}

registerProcessor('audio-processor', AudioProcessorWorklet);

// 主线程代码
async function startAudioRecording() {
    const stream = await navigator.mediaDevices.getUserMedia({
        audio: {
            echoCancellation: true,
            noiseSuppression: true,
            autoGainControl: true,
            sampleRate: 48000
        }
    });

    const audioContext = new AudioContext();
    const audioSource = audioContext.createMediaStreamSource(stream);

    await audioContext.audioWorklet.addModule('/audio-worklet.js');
    const audioWorkletNode = new AudioWorkletNode(audioContext, 'audio-processor');

    audioWorkletNode.port.onmessage = (event) => {
        if (event.data.type === 'audioData' && ws?.readyState === WebSocket.OPEN) {
            ws.send(event.data.data); // 直接发送二进制数据
        }
    };

    audioSource.connect(audioWorkletNode);
}

AudioWorklet 比 ScriptProcessorNode 性能好很多，不会有音频卡顿的问题。这年代，谁还愿意听那种刺刺拉拉的噪音呢？

后端配置

appsettings.json 示例

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": { "path": "logs/log-.txt", "rollingInterval": "Day" }
      }
    ]
  },
  "Kestrel": {
    "Urls": "http://0.0.0.0:5000"
  }
}

日志配置很重要，方便排查问题。Serilog 的 File sink 可以按天滚动，日志文件也不会太大。毕竟有些问题嘛，事后诸葛亮总是要容易一点的。

注意事项和最佳实践

1. 连接监控

定期输出会话状态日志，方便追踪连接生命周期
监控音频段数量和持续时间，识别异常连接
记录与豆包服务的连接状态和重连情况

这些也就是一些基本的操作罢了。

2. 错误处理

捕获并记录所有 WebSocket 异常
使用 IAsyncDisposable 确保资源清理
实现优雅的连接关闭和超时处理

总而言之，稳字当头。

3. 音频格式要求

采样率：16000 Hz（推荐）或 8000 Hz
位深度：16-bit
声道：单声道
编码：PCM (raw)

格式不对会导致识别失败或者效果很差。这点儿规矩还是要守的。

4. 安全考虑

敏感凭证只存在后端配置里
实施连接数限制防止资源耗尽
生产环境用 HTTPS/WSS

安全无小事，且行且珍惜罢。

5. 性能优化

用异步操作避免阻塞
适当调整缓冲区大小（默认 4096 字节）
考虑连接池和复用策略

这些优化手段，能用上的就用上罢。

部署建议

Docker 部署：把代理服务打包成容器，方便扩展和管理
负载均衡：用 Nginx 或 Envoy 做 WebSocket 反向代理
健康检查：实现心跳机制监控服务可用性
日志聚合：把日志发送到集中式日志系统（如 ELK、Loki）

部署这事儿吧，说简单也简单，说复杂也复杂。也就是因人而异，因地制宜罢。

总结

WebSocket 代理方案解决了浏览器 WebSocket API 不支持自定义 header 的根本问题。在 HagiCode 项目中，这个方案从 playground 验证到生产环境部署，证明了它的可行性和稳定性。

关键点总结：

后端代理可以安全地传递认证信息
原生 WebSocket 轻量高效，适合简单场景
“每连接单会话”简化了实现和调试
前后端消息协议分离控制信号和音频数据

如果你也在做需要 WebSocket 认证的功能，希望这个方案能给你一些启发。

有什么问题的话，欢迎来讨论。毕竟技术这东西嘛，都是在交流中进步的。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://docs.hagicode.com/blog/2026-03-05-websocket-proxy-for-doubao-speech-recognition/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!