SenseVoice-Small模型在.NET生态中的调用C#客户端开发详解最近在做一个智能客服项目需要集成语音转文字功能。调研了一圈发现SenseVoice-Small这个模型在中文语音识别上表现不错而且提供了标准的HTTP API接口。作为.NET开发者第一反应就是怎么用C#把它调起来其实过程比想象中简单。今天我就把自己踩过的坑和总结出来的方法用最直白的方式分享给你。不管你是想在控制台程序里快速测试还是要在ASP.NET Core Web API里集成看完这篇都能搞定。1. 准备工作先搞清楚我们要做什么在写代码之前咱们先花两分钟了解一下SenseVoice-Small这个模型和它的接口。这样后面写代码的时候你才知道每一步在干什么。SenseVoice-Small是一个专门做语音识别的模型你给它一段音频它就能把里面的说话内容转成文字。它对外提供了一个HTTP接口我们只需要按照它的要求把音频文件传过去然后等它返回识别结果就行。这个接口有几个关键点你需要知道请求方式用的是HTTP POST。数据格式需要以“表单数据”的形式上传具体来说是multipart/form-data。这就像在网页上上传文件一样。主要参数基本上你只需要关心一个叫audio的参数把你要识别的音频文件传给它就行。模型支持常见的音频格式比如WAV、MP3这些。返回结果接口处理完后会返回一个JSON格式的数据里面就包含了识别出来的文字。对我们.NET开发者来说核心任务就三件事用C#把音频文件打包成一个HTTP请求发出去。安安静静地等模型处理完。把返回的JSON数据解析出来拿到我们想要的文字。听起来是不是挺简单的接下来我们就一步步实现它。2. 搭建你的开发环境工欲善其事必先利其器。写代码前先把环境准备好。这里我不假设你是新手还是老手咱们从最基础的开始。首先你需要一个.NET开发环境。如果你还没有可以去微软官网下载最新的.NET SDK和Visual Studio社区版是免费的。用Visual Studio Code也可以看个人喜好。今天我们会创建两个示例项目为了清晰起见我建议你在电脑上新建一个文件夹比如叫SenseVoiceDemo然后在这个文件夹里操作。第一个项目我们用一个简单的控制台应用来快速测试和验证接口调用是否成功。打开你的终端命令提示符、PowerShell或VS Code的终端都行进入刚才创建的文件夹运行下面这条命令dotnet new console -n SenseVoiceConsoleClient这条命令会创建一个名为SenseVoiceConsoleClient的新控制台项目。创建成功后进入这个项目文件夹cd SenseVoiceConsoleClient现在我们需要安装一个非常重要的NuGet包Newtonsoft.Json。虽然.NET Core之后有自带的System.Text.Json但Newtonsoft.Json用起来更顺手生态也更成熟我们用它来解析返回的JSON数据。在项目文件夹里运行dotnet add package Newtonsoft.Json好了控制台项目的架子就搭好了。先别急着写代码我们再来准备第二个项目。3. 核心方法用HttpClient发送请求这是整个教程最核心的部分。无论你最终是在控制台还是Web API里调用发送HTTP请求的逻辑都是共通的。我把它封装成了一个独立的方法你可以直接复制过去用。在SenseVoiceConsoleClient项目里找到Program.cs文件把里面的代码全部替换成下面的内容。我会逐行给你解释关键部分。using System; using System.IO; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; namespace SenseVoiceConsoleClient { class Program { // 这是SenseVoice-Small模型的API地址你需要替换成你自己的 private static readonly string ApiUrl YOUR_SENSEVOICE_API_ENDPOINT_HERE; static async Task Main(string[] args) { Console.WriteLine(SenseVoice-Small 语音识别客户端); Console.WriteLine(); // 指定要识别的音频文件路径 string audioFilePath C:\path\to\your\audio.wav; // 请修改为你的实际文件路径 if (!File.Exists(audioFilePath)) { Console.WriteLine($错误找不到音频文件 {audioFilePath}); return; } try { Console.WriteLine($正在处理文件: {audioFilePath}); // 调用核心方法进行识别 string result await TranscribeAudioAsync(audioFilePath); Console.WriteLine(\n识别结果); Console.WriteLine(----------); Console.WriteLine(result); } catch (Exception ex) { Console.WriteLine($处理过程中发生错误: {ex.Message}); } Console.WriteLine(\n按任意键退出...); Console.ReadKey(); } /// summary /// 调用SenseVoice-Small API进行语音识别的核心方法 /// /summary /// param nameaudioFilePath音频文件的完整路径/param /// returns识别出的文本内容/returns public static async Taskstring TranscribeAudioAsync(string audioFilePath) { // 1. 创建HttpClient实例建议复用而不是每次new using (var httpClient new HttpClient()) { // 2. 准备表单数据用于上传文件 using (var formData new MultipartFormDataContent()) { // 读取音频文件为字节流 byte[] audioBytes await File.ReadAllBytesAsync(audioFilePath); // 创建文件内容对象 var fileContent new ByteArrayContent(audioBytes); // 这里很重要需要设置Content-Type告诉服务器这是音频文件 // 你可以根据你的文件类型调整比如audio/mpeg for mp3 fileContent.Headers.ContentType new System.Net.Http.Headers.MediaTypeHeaderValue(audio/wav); // 将文件内容添加到表单中参数名必须为audio formData.Add(fileContent, audio, Path.GetFileName(audioFilePath)); Console.WriteLine(正在发送请求到API...); // 3. 发送POST请求 HttpResponseMessage response await httpClient.PostAsync(ApiUrl, formData); // 4. 检查响应是否成功 if (!response.IsSuccessStatusCode) { // 如果失败抛出异常并包含状态码和原因 throw new HttpRequestException($API请求失败状态码: {(int)response.StatusCode} - {response.ReasonPhrase}); } Console.WriteLine(请求成功正在解析响应...); // 5. 读取返回的JSON字符串 string responseBody await response.Content.ReadAsStringAsync(); // 6. 解析JSON提取识别文本 // 这里假设返回的JSON结构里有一个text字段存放结果 // 实际结构需要根据API文档调整 JObject jsonResult JObject.Parse(responseBody); string transcribedText jsonResult[text]?.Valuestring(); // 根据实际返回的字段名调整 if (string.IsNullOrEmpty(transcribedText)) { // 如果没拿到文本可能是JSON结构不对或者识别为空 throw new InvalidDataException(API返回了成功响应但未找到有效的识别文本。返回内容为 responseBody); } return transcribedText; } } } } }上面这段代码就是我们的核心武器。我来给你划一下重点第35行ApiUrl这是最关键的一行你得把它换成真实的SenseVoice-Small API地址。这个地址通常由提供模型服务的平台给你。第45行audioFilePath这里要改成你电脑上真实存在的音频文件路径。比如你有一个叫test.wav的文件放在桌面路径可能就是C:\Users\你的用户名\Desktop\test.wav。核心方法TranscribeAudioAsync这个方法干了所有重活。它创建了一个HttpClient把音频文件打包成表单发送POST请求然后处理返回的JSON。文件上传部分第70-80行我们用MultipartFormDataContent来模拟网页表单上传文件。注意formData.Add的第二个参数是audio这必须和API要求的参数名一致。第三个参数是文件名。JSON解析部分第100-104行这里用Newtonsoft.Json来解析返回的数据。我假设返回的JSON里有一个text字段装着识别结果。这一点非常重要你需要根据你使用的SenseVoice-Small API的实际返回格式来调整这里的字段名。比如有的接口可能叫result或者transcription。代码准备好了但在运行之前还有两个小地方要修改把第35行的YOUR_SENSEVOICE_API_ENDPOINT_HERE替换成你的真实API地址。把第45行的C:\path\to\your\audio.wav替换成你准备好的测试音频文件路径。保存文件然后在终端里运行dotnet run如果一切顺利你应该能看到控制台输出“正在发送请求到API...”然后稍等片刻就能看到模型识别出来的文字了。恭喜你最核心的一步已经完成了4. 进阶实战集成到ASP.NET Core Web API控制台测试成功了说明我们的调用逻辑没问题。但在实际项目中比如我开头说的智能客服系统我们更可能需要一个Web API服务来提供语音识别功能。这样前端网页、手机App或者其他服务都能来调用。接下来我们就快速搭建一个ASP.NET Core Web API把刚才的识别能力封装成一个HTTP接口。首先退出刚才的控制台项目文件夹回到我们最初创建的SenseVoiceDemo目录。然后运行以下命令创建一个新的Web API项目dotnet new webapi -n SenseVoiceWebApi cd SenseVoiceWebApi同样我们需要安装JSON解析的包dotnet add package Newtonsoft.Json创建好后我们主要需要做两件事一是创建一个控制器Controller来处理请求二是把刚才写好的核心识别方法搬过来。第一步创建控制器。在Controllers文件夹上右键选择“添加” - “控制器”或者直接新建一个类文件命名为SpeechRecognitionController.cs。然后把下面的代码贴进去using Microsoft.AspNetCore.Mvc; using System; using System.IO; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; namespace SenseVoiceWebApi.Controllers { [ApiController] [Route(api/[controller])] // 访问路径会是 /api/SpeechRecognition public class SpeechRecognitionController : ControllerBase { private static readonly string SenseVoiceApiUrl YOUR_SENSEVOICE_API_ENDPOINT_HERE; private readonly IHttpClientFactory _httpClientFactory; // 通过依赖注入获取HttpClientFactory这是更推荐的做法 public SpeechRecognitionController(IHttpClientFactory httpClientFactory) { _httpClientFactory httpClientFactory; } [HttpPost(transcribe)] public async TaskIActionResult TranscribeAudio(IFormFile audioFile) { // 1. 检查前端是否上传了文件 if (audioFile null || audioFile.Length 0) { return BadRequest(请上传一个有效的音频文件。); } // 2. 检查文件类型可选但建议做 var allowedExtensions new[] { .wav, .mp3, .m4a, .flac }; var fileExtension Path.GetExtension(audioFile.FileName).ToLower(); if (!allowedExtensions.Contains(fileExtension)) { return BadRequest($不支持的文件格式。请上传以下格式{string.Join(, , allowedExtensions)}); } try { Console.WriteLine($开始处理上传文件: {audioFile.FileName}); // 3. 调用识别方法 string transcribedText await CallSenseVoiceApiAsync(audioFile); // 4. 返回识别结果 return Ok(new { success true, text transcribedText }); } catch (HttpRequestException httpEx) { // 处理网络或API错误 return StatusCode(500, new { success false, error $语音识别服务调用失败: {httpEx.Message} }); } catch (Exception ex) { // 处理其他未知错误 return StatusCode(500, new { success false, error $处理过程中发生错误: {ex.Message} }); } } private async Taskstring CallSenseVoiceApiAsync(IFormFile audioFile) { // 使用IHttpClientFactory创建Client有利于连接管理 var httpClient _httpClientFactory.CreateClient(); using (var formData new MultipartFormDataContent()) { // 将上传的文件流读取到内存中 using (var memoryStream new MemoryStream()) { await audioFile.CopyToAsync(memoryStream); var fileContent new ByteArrayContent(memoryStream.ToArray()); // 根据文件后缀设置Content-Type string contentType GetContentType(audioFile.FileName); fileContent.Headers.ContentType new System.Net.Http.Headers.MediaTypeHeaderValue(contentType); formData.Add(fileContent, audio, audioFile.FileName); HttpResponseMessage response await httpClient.PostAsync(SenseVoiceApiUrl, formData); response.EnsureSuccessStatusCode(); // 如果状态码不成功会抛出异常 string responseBody await response.Content.ReadAsStringAsync(); JObject jsonResult JObject.Parse(responseBody); string transcribedText jsonResult[text]?.Valuestring(); // 根据实际API调整字段名 if (string.IsNullOrEmpty(transcribedText)) { throw new InvalidDataException(API返回了成功响应但未找到有效的识别文本。); } return transcribedText; } } } private string GetContentType(string fileName) { // 简单的映射将文件扩展名映射为对应的MIME类型 string extension Path.GetExtension(fileName).ToLower(); return extension switch { .wav audio/wav, .mp3 audio/mpeg, .m4a audio/mp4, .flac audio/flac, _ application/octet-stream // 默认类型 }; } } }第二步注册HttpClientFactory。为了让控制器能正常工作我们需要在Program.cs文件中添加一行服务注册代码。打开Program.cs在var builder WebApplication.CreateBuilder(args);这行代码之后添加服务// 添加HttpClientFactory服务 builder.Services.AddHttpClient();现在你的Web API项目就准备好了。别忘了把代码第13行的YOUR_SENSEVOICE_API_ENDPOINT_HERE换成真实的地址。第三步运行并测试。在项目根目录下运行dotnet run你会看到应用启动并监听某个端口通常是https://localhost:7079和http://localhost:5256。怎么测试呢最简单的方法是使用Postman或者任何你喜欢的API测试工具。创建一个POST请求地址是http://localhost:5256/api/SpeechRecognition/transcribe如果你用HTTPS就换成对应的地址。将Body类型设置为form-data。添加一个Key名字设为audioFile注意这个名字必须和控制器方法参数IFormFile audioFile里的audioFile一致类型选择File。在Value那里选择你电脑上的一个音频文件。点击发送。如果成功你会收到一个JSON响应里面包含了识别出的文字。这样一个简单的语音识别Web服务就搭建完成了。前端或其他服务现在都可以通过调用这个接口来获得语音转文字的功能。5. 你可能遇到的问题和解决办法在实际开发中你几乎肯定会遇到一些问题。下面是我在集成过程中遇到的几个典型问题及其解决方法希望能帮你省点时间。问题一API返回错误比如“Invalid audio file”或“Unsupported format”。这通常意味着你上传的音频文件不符合模型的要求。检查音频格式确认你的文件是模型支持的格式如WAV、MP3。即使扩展名正确文件本身也可能损坏。可以用播放器打开试试。检查编码参数有些模型对音频的采样率如必须是16kHz、位深或声道数有要求。你可以用像Audacity这样的免费音频编辑软件查看和转换这些参数。在代码中我们上面写的GetContentType方法只是根据文件后缀设置请求头确保这个映射是正确的。如果API特别挑剔你可能需要精确设置Content-Type比如audio/wav; codecpcm。问题二请求超时长时间没响应。语音识别可能需要几秒到几十秒取决于音频长度和服务器负载。增加超时设置在创建HttpClient时可以配置一个更长的超时时间。var httpClient _httpClientFactory.CreateClient(); httpClient.Timeout TimeSpan.FromSeconds(60); // 设置为60秒考虑异步处理对于很长的音频同步等待可能不是好主意。你可以考虑采用“提交任务-返回任务ID-客户端轮询结果”的异步模式但这需要后端API支持。问题三解析JSON时出错提示找不到字段。这是最常见的问题之一意味着你的代码期望的JSON结构和API实际返回的不一样。打印原始响应在解析之前先把responseBody打印出来看看。修改代码在JObject.Parse(responseBody)之前加一行Console.WriteLine(Raw Response: responseBody);。仔细阅读API文档查看官方文档确认成功响应和错误响应的具体JSON结构。字段名可能是text、result、transcription或者嵌套在某个对象里。使用动态解析如果不确定结构可以用dynamic关键字来安全地访问但会损失类型安全dynamic result JObject.Parse(responseBody); string text result?.text ?? result?.result?.text; // 尝试多种可能路径问题四在Web API中上传大文件失败。ASP.NET Core默认对请求大小和文件上传有限制。调整配置在Program.cs中添加以下代码来增大限制例如允许100MB的文件builder.Services.ConfigureFormOptions(options { options.MultipartBodyLengthLimit 104857600; // 100 MB });同时如果你使用Kestrel服务器可能还需要配置builder.WebHost.ConfigureKestrel(serverOptions { serverOptions.Limits.MaxRequestBodySize 104857600; // 100 MB });问题五性能问题感觉每次调用都很慢。复用HttpClient千万不要在每次请求里都new HttpClient()。在我们的Web API示例中使用IHttpClientFactory是正确且推荐的做法它能高效管理HTTP连接。考虑并发和限流如果你的应用需要高并发调用语音识别API要注意对方服务器可能有速率限制。你需要在自己的代码里实现重试机制和并发控制。把这些问题和解决方法记在心里能让你在调试的时候更有方向。6. 总结与后续可以做的事走完上面这些步骤你应该已经成功在.NET环境里调通了SenseVoice-Small的语音识别功能。从最开始的简单控制台测试到后来封装成一个独立的Web API服务这个过程其实也是大多数服务集成的基本路径先验证核心功能再构建生产可用的接口。用下来感觉整个集成过程的关键点就几个正确构造HTTP请求、处理好文件上传格式、耐心调试API返回的数据结构。只要这几点搞定了剩下的就是业务逻辑的组装。如果你还想把这个功能做得更完善这里有几个可以继续探索的方向。比如给Web API加上身份验证像JWT这样不是谁都能来调用你的服务。或者增加一个文件存储功能把用户上传的音频和识别结果存到数据库里方便后续查询和管理。再进一步你可以考虑引入消息队列如RabbitMQ把识别请求丢到队列里异步处理这样用户就不用长时间等待特别适合处理长音频。最后代码的安全性也要留意。我们示例里为了清晰把API地址直接写在了代码里。在实际项目中你应该把它放到配置文件如appsettings.json或者环境变量里避免敏感信息泄露。希望这篇教程能帮你顺利起步。语音识别现在用到的场景越来越多从会议记录到客服质检能做的事情不少。如果你在集成过程中遇到了其他问题或者有更好的实现方法也欢迎一起交流。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
SenseVoice-Small模型在.NET生态中的调用：C#客户端开发详解
发布时间：2026/6/22 14:35:30
SenseVoice-Small模型在.NET生态中的调用C#客户端开发详解最近在做一个智能客服项目需要集成语音转文字功能。调研了一圈发现SenseVoice-Small这个模型在中文语音识别上表现不错而且提供了标准的HTTP API接口。作为.NET开发者第一反应就是怎么用C#把它调起来其实过程比想象中简单。今天我就把自己踩过的坑和总结出来的方法用最直白的方式分享给你。不管你是想在控制台程序里快速测试还是要在ASP.NET Core Web API里集成看完这篇都能搞定。1. 准备工作先搞清楚我们要做什么在写代码之前咱们先花两分钟了解一下SenseVoice-Small这个模型和它的接口。这样后面写代码的时候你才知道每一步在干什么。SenseVoice-Small是一个专门做语音识别的模型你给它一段音频它就能把里面的说话内容转成文字。它对外提供了一个HTTP接口我们只需要按照它的要求把音频文件传过去然后等它返回识别结果就行。这个接口有几个关键点你需要知道请求方式用的是HTTP POST。数据格式需要以“表单数据”的形式上传具体来说是multipart/form-data。这就像在网页上上传文件一样。主要参数基本上你只需要关心一个叫audio的参数把你要识别的音频文件传给它就行。模型支持常见的音频格式比如WAV、MP3这些。返回结果接口处理完后会返回一个JSON格式的数据里面就包含了识别出来的文字。对我们.NET开发者来说核心任务就三件事用C#把音频文件打包成一个HTTP请求发出去。安安静静地等模型处理完。把返回的JSON数据解析出来拿到我们想要的文字。听起来是不是挺简单的接下来我们就一步步实现它。2. 搭建你的开发环境工欲善其事必先利其器。写代码前先把环境准备好。这里我不假设你是新手还是老手咱们从最基础的开始。首先你需要一个.NET开发环境。如果你还没有可以去微软官网下载最新的.NET SDK和Visual Studio社区版是免费的。用Visual Studio Code也可以看个人喜好。今天我们会创建两个示例项目为了清晰起见我建议你在电脑上新建一个文件夹比如叫SenseVoiceDemo然后在这个文件夹里操作。第一个项目我们用一个简单的控制台应用来快速测试和验证接口调用是否成功。打开你的终端命令提示符、PowerShell或VS Code的终端都行进入刚才创建的文件夹运行下面这条命令dotnet new console -n SenseVoiceConsoleClient这条命令会创建一个名为SenseVoiceConsoleClient的新控制台项目。创建成功后进入这个项目文件夹cd SenseVoiceConsoleClient现在我们需要安装一个非常重要的NuGet包Newtonsoft.Json。虽然.NET Core之后有自带的System.Text.Json但Newtonsoft.Json用起来更顺手生态也更成熟我们用它来解析返回的JSON数据。在项目文件夹里运行dotnet add package Newtonsoft.Json好了控制台项目的架子就搭好了。先别急着写代码我们再来准备第二个项目。3. 核心方法用HttpClient发送请求这是整个教程最核心的部分。无论你最终是在控制台还是Web API里调用发送HTTP请求的逻辑都是共通的。我把它封装成了一个独立的方法你可以直接复制过去用。在SenseVoiceConsoleClient项目里找到Program.cs文件把里面的代码全部替换成下面的内容。我会逐行给你解释关键部分。using System; using System.IO; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; namespace SenseVoiceConsoleClient { class Program { // 这是SenseVoice-Small模型的API地址你需要替换成你自己的 private static readonly string ApiUrl YOUR_SENSEVOICE_API_ENDPOINT_HERE; static async Task Main(string[] args) { Console.WriteLine(SenseVoice-Small 语音识别客户端); Console.WriteLine(); // 指定要识别的音频文件路径 string audioFilePath C:\path\to\your\audio.wav; // 请修改为你的实际文件路径 if (!File.Exists(audioFilePath)) { Console.WriteLine($错误找不到音频文件 {audioFilePath}); return; } try { Console.WriteLine($正在处理文件: {audioFilePath}); // 调用核心方法进行识别 string result await TranscribeAudioAsync(audioFilePath); Console.WriteLine(\n识别结果); Console.WriteLine(----------); Console.WriteLine(result); } catch (Exception ex) { Console.WriteLine($处理过程中发生错误: {ex.Message}); } Console.WriteLine(\n按任意键退出...); Console.ReadKey(); } /// summary /// 调用SenseVoice-Small API进行语音识别的核心方法 /// /summary /// param nameaudioFilePath音频文件的完整路径/param /// returns识别出的文本内容/returns public static async Taskstring TranscribeAudioAsync(string audioFilePath) { // 1. 创建HttpClient实例建议复用而不是每次new using (var httpClient new HttpClient()) { // 2. 准备表单数据用于上传文件 using (var formData new MultipartFormDataContent()) { // 读取音频文件为字节流 byte[] audioBytes await File.ReadAllBytesAsync(audioFilePath); // 创建文件内容对象 var fileContent new ByteArrayContent(audioBytes); // 这里很重要需要设置Content-Type告诉服务器这是音频文件 // 你可以根据你的文件类型调整比如audio/mpeg for mp3 fileContent.Headers.ContentType new System.Net.Http.Headers.MediaTypeHeaderValue(audio/wav); // 将文件内容添加到表单中参数名必须为audio formData.Add(fileContent, audio, Path.GetFileName(audioFilePath)); Console.WriteLine(正在发送请求到API...); // 3. 发送POST请求 HttpResponseMessage response await httpClient.PostAsync(ApiUrl, formData); // 4. 检查响应是否成功 if (!response.IsSuccessStatusCode) { // 如果失败抛出异常并包含状态码和原因 throw new HttpRequestException($API请求失败状态码: {(int)response.StatusCode} - {response.ReasonPhrase}); } Console.WriteLine(请求成功正在解析响应...); // 5. 读取返回的JSON字符串 string responseBody await response.Content.ReadAsStringAsync(); // 6. 解析JSON提取识别文本 // 这里假设返回的JSON结构里有一个text字段存放结果 // 实际结构需要根据API文档调整 JObject jsonResult JObject.Parse(responseBody); string transcribedText jsonResult[text]?.Valuestring(); // 根据实际返回的字段名调整 if (string.IsNullOrEmpty(transcribedText)) { // 如果没拿到文本可能是JSON结构不对或者识别为空 throw new InvalidDataException(API返回了成功响应但未找到有效的识别文本。返回内容为 responseBody); } return transcribedText; } } } } }上面这段代码就是我们的核心武器。我来给你划一下重点第35行ApiUrl这是最关键的一行你得把它换成真实的SenseVoice-Small API地址。这个地址通常由提供模型服务的平台给你。第45行audioFilePath这里要改成你电脑上真实存在的音频文件路径。比如你有一个叫test.wav的文件放在桌面路径可能就是C:\Users\你的用户名\Desktop\test.wav。核心方法TranscribeAudioAsync这个方法干了所有重活。它创建了一个HttpClient把音频文件打包成表单发送POST请求然后处理返回的JSON。文件上传部分第70-80行我们用MultipartFormDataContent来模拟网页表单上传文件。注意formData.Add的第二个参数是audio这必须和API要求的参数名一致。第三个参数是文件名。JSON解析部分第100-104行这里用Newtonsoft.Json来解析返回的数据。我假设返回的JSON里有一个text字段装着识别结果。这一点非常重要你需要根据你使用的SenseVoice-Small API的实际返回格式来调整这里的字段名。比如有的接口可能叫result或者transcription。代码准备好了但在运行之前还有两个小地方要修改把第35行的YOUR_SENSEVOICE_API_ENDPOINT_HERE替换成你的真实API地址。把第45行的C:\path\to\your\audio.wav替换成你准备好的测试音频文件路径。保存文件然后在终端里运行dotnet run如果一切顺利你应该能看到控制台输出“正在发送请求到API...”然后稍等片刻就能看到模型识别出来的文字了。恭喜你最核心的一步已经完成了4. 进阶实战集成到ASP.NET Core Web API控制台测试成功了说明我们的调用逻辑没问题。但在实际项目中比如我开头说的智能客服系统我们更可能需要一个Web API服务来提供语音识别功能。这样前端网页、手机App或者其他服务都能来调用。接下来我们就快速搭建一个ASP.NET Core Web API把刚才的识别能力封装成一个HTTP接口。首先退出刚才的控制台项目文件夹回到我们最初创建的SenseVoiceDemo目录。然后运行以下命令创建一个新的Web API项目dotnet new webapi -n SenseVoiceWebApi cd SenseVoiceWebApi同样我们需要安装JSON解析的包dotnet add package Newtonsoft.Json创建好后我们主要需要做两件事一是创建一个控制器Controller来处理请求二是把刚才写好的核心识别方法搬过来。第一步创建控制器。在Controllers文件夹上右键选择“添加” - “控制器”或者直接新建一个类文件命名为SpeechRecognitionController.cs。然后把下面的代码贴进去using Microsoft.AspNetCore.Mvc; using System; using System.IO; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; namespace SenseVoiceWebApi.Controllers { [ApiController] [Route(api/[controller])] // 访问路径会是 /api/SpeechRecognition public class SpeechRecognitionController : ControllerBase { private static readonly string SenseVoiceApiUrl YOUR_SENSEVOICE_API_ENDPOINT_HERE; private readonly IHttpClientFactory _httpClientFactory; // 通过依赖注入获取HttpClientFactory这是更推荐的做法 public SpeechRecognitionController(IHttpClientFactory httpClientFactory) { _httpClientFactory httpClientFactory; } [HttpPost(transcribe)] public async TaskIActionResult TranscribeAudio(IFormFile audioFile) { // 1. 检查前端是否上传了文件 if (audioFile null || audioFile.Length 0) { return BadRequest(请上传一个有效的音频文件。); } // 2. 检查文件类型可选但建议做 var allowedExtensions new[] { .wav, .mp3, .m4a, .flac }; var fileExtension Path.GetExtension(audioFile.FileName).ToLower(); if (!allowedExtensions.Contains(fileExtension)) { return BadRequest($不支持的文件格式。请上传以下格式{string.Join(, , allowedExtensions)}); } try { Console.WriteLine($开始处理上传文件: {audioFile.FileName}); // 3. 调用识别方法 string transcribedText await CallSenseVoiceApiAsync(audioFile); // 4. 返回识别结果 return Ok(new { success true, text transcribedText }); } catch (HttpRequestException httpEx) { // 处理网络或API错误 return StatusCode(500, new { success false, error $语音识别服务调用失败: {httpEx.Message} }); } catch (Exception ex) { // 处理其他未知错误 return StatusCode(500, new { success false, error $处理过程中发生错误: {ex.Message} }); } } private async Taskstring CallSenseVoiceApiAsync(IFormFile audioFile) { // 使用IHttpClientFactory创建Client有利于连接管理 var httpClient _httpClientFactory.CreateClient(); using (var formData new MultipartFormDataContent()) { // 将上传的文件流读取到内存中 using (var memoryStream new MemoryStream()) { await audioFile.CopyToAsync(memoryStream); var fileContent new ByteArrayContent(memoryStream.ToArray()); // 根据文件后缀设置Content-Type string contentType GetContentType(audioFile.FileName); fileContent.Headers.ContentType new System.Net.Http.Headers.MediaTypeHeaderValue(contentType); formData.Add(fileContent, audio, audioFile.FileName); HttpResponseMessage response await httpClient.PostAsync(SenseVoiceApiUrl, formData); response.EnsureSuccessStatusCode(); // 如果状态码不成功会抛出异常 string responseBody await response.Content.ReadAsStringAsync(); JObject jsonResult JObject.Parse(responseBody); string transcribedText jsonResult[text]?.Valuestring(); // 根据实际API调整字段名 if (string.IsNullOrEmpty(transcribedText)) { throw new InvalidDataException(API返回了成功响应但未找到有效的识别文本。); } return transcribedText; } } } private string GetContentType(string fileName) { // 简单的映射将文件扩展名映射为对应的MIME类型 string extension Path.GetExtension(fileName).ToLower(); return extension switch { .wav audio/wav, .mp3 audio/mpeg, .m4a audio/mp4, .flac audio/flac, _ application/octet-stream // 默认类型 }; } } }第二步注册HttpClientFactory。为了让控制器能正常工作我们需要在Program.cs文件中添加一行服务注册代码。打开Program.cs在var builder WebApplication.CreateBuilder(args);这行代码之后添加服务// 添加HttpClientFactory服务 builder.Services.AddHttpClient();现在你的Web API项目就准备好了。别忘了把代码第13行的YOUR_SENSEVOICE_API_ENDPOINT_HERE换成真实的地址。第三步运行并测试。在项目根目录下运行dotnet run你会看到应用启动并监听某个端口通常是https://localhost:7079和http://localhost:5256。怎么测试呢最简单的方法是使用Postman或者任何你喜欢的API测试工具。创建一个POST请求地址是http://localhost:5256/api/SpeechRecognition/transcribe如果你用HTTPS就换成对应的地址。将Body类型设置为form-data。添加一个Key名字设为audioFile注意这个名字必须和控制器方法参数IFormFile audioFile里的audioFile一致类型选择File。在Value那里选择你电脑上的一个音频文件。点击发送。如果成功你会收到一个JSON响应里面包含了识别出的文字。这样一个简单的语音识别Web服务就搭建完成了。前端或其他服务现在都可以通过调用这个接口来获得语音转文字的功能。5. 你可能遇到的问题和解决办法在实际开发中你几乎肯定会遇到一些问题。下面是我在集成过程中遇到的几个典型问题及其解决方法希望能帮你省点时间。问题一API返回错误比如“Invalid audio file”或“Unsupported format”。这通常意味着你上传的音频文件不符合模型的要求。检查音频格式确认你的文件是模型支持的格式如WAV、MP3。即使扩展名正确文件本身也可能损坏。可以用播放器打开试试。检查编码参数有些模型对音频的采样率如必须是16kHz、位深或声道数有要求。你可以用像Audacity这样的免费音频编辑软件查看和转换这些参数。在代码中我们上面写的GetContentType方法只是根据文件后缀设置请求头确保这个映射是正确的。如果API特别挑剔你可能需要精确设置Content-Type比如audio/wav; codecpcm。问题二请求超时长时间没响应。语音识别可能需要几秒到几十秒取决于音频长度和服务器负载。增加超时设置在创建HttpClient时可以配置一个更长的超时时间。var httpClient _httpClientFactory.CreateClient(); httpClient.Timeout TimeSpan.FromSeconds(60); // 设置为60秒考虑异步处理对于很长的音频同步等待可能不是好主意。你可以考虑采用“提交任务-返回任务ID-客户端轮询结果”的异步模式但这需要后端API支持。问题三解析JSON时出错提示找不到字段。这是最常见的问题之一意味着你的代码期望的JSON结构和API实际返回的不一样。打印原始响应在解析之前先把responseBody打印出来看看。修改代码在JObject.Parse(responseBody)之前加一行Console.WriteLine(Raw Response: responseBody);。仔细阅读API文档查看官方文档确认成功响应和错误响应的具体JSON结构。字段名可能是text、result、transcription或者嵌套在某个对象里。使用动态解析如果不确定结构可以用dynamic关键字来安全地访问但会损失类型安全dynamic result JObject.Parse(responseBody); string text result?.text ?? result?.result?.text; // 尝试多种可能路径问题四在Web API中上传大文件失败。ASP.NET Core默认对请求大小和文件上传有限制。调整配置在Program.cs中添加以下代码来增大限制例如允许100MB的文件builder.Services.ConfigureFormOptions(options { options.MultipartBodyLengthLimit 104857600; // 100 MB });同时如果你使用Kestrel服务器可能还需要配置builder.WebHost.ConfigureKestrel(serverOptions { serverOptions.Limits.MaxRequestBodySize 104857600; // 100 MB });问题五性能问题感觉每次调用都很慢。复用HttpClient千万不要在每次请求里都new HttpClient()。在我们的Web API示例中使用IHttpClientFactory是正确且推荐的做法它能高效管理HTTP连接。考虑并发和限流如果你的应用需要高并发调用语音识别API要注意对方服务器可能有速率限制。你需要在自己的代码里实现重试机制和并发控制。把这些问题和解决方法记在心里能让你在调试的时候更有方向。6. 总结与后续可以做的事走完上面这些步骤你应该已经成功在.NET环境里调通了SenseVoice-Small的语音识别功能。从最开始的简单控制台测试到后来封装成一个独立的Web API服务这个过程其实也是大多数服务集成的基本路径先验证核心功能再构建生产可用的接口。用下来感觉整个集成过程的关键点就几个正确构造HTTP请求、处理好文件上传格式、耐心调试API返回的数据结构。只要这几点搞定了剩下的就是业务逻辑的组装。如果你还想把这个功能做得更完善这里有几个可以继续探索的方向。比如给Web API加上身份验证像JWT这样不是谁都能来调用你的服务。或者增加一个文件存储功能把用户上传的音频和识别结果存到数据库里方便后续查询和管理。再进一步你可以考虑引入消息队列如RabbitMQ把识别请求丢到队列里异步处理这样用户就不用长时间等待特别适合处理长音频。最后代码的安全性也要留意。我们示例里为了清晰把API地址直接写在了代码里。在实际项目中你应该把它放到配置文件如appsettings.json或者环境变量里避免敏感信息泄露。希望这篇教程能帮你顺利起步。语音识别现在用到的场景越来越多从会议记录到客服质检能做的事情不少。如果你在集成过程中遇到了其他问题或者有更好的实现方法也欢迎一起交流。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
