当前位置：首页 > news >正文

文墨共鸣大模型快速开发：.NET后端集成与API封装

news 2026/5/12 17:49:43

文墨共鸣大模型快速开发：.NET后端集成与API封装

最近在做一个需要集成大语言模型的项目，后端用的是.NET技术栈。市面上很多教程都是Python的，对.NET开发者不太友好。其实用ASP.NET Core来封装大模型调用，既简单又高效，还能很好地融入现有的微服务架构。今天我就结合自己的实践，聊聊怎么在ASP.NET Core Web API项目里，优雅地集成文墨共鸣这类大模型服务，重点是实现稳定、可维护的HTTP调用和酷炫的流式响应。

1. 项目准备与环境搭建

在开始写代码之前，得先把基础环境准备好。这个过程不复杂，跟着步骤走就行。

1.1 创建项目与安装包

首先，打开Visual Studio或者直接用.NET CLI，创建一个新的ASP.NET Core Web API项目。我习惯用CLI，命令简单明了：

dotnet new webapi -n AILanguageService cd AILanguageService

创建好项目后，需要安装几个必要的NuGet包。主要用到的是Microsoft.Extensions.Http，它提供了HttpClientFactory，这是管理HTTP客户端生命周期的“神器”，能有效避免端口耗尽和DNS刷新问题。直接在项目目录下运行：

dotnet add package Microsoft.Extensions.Http

如果你的项目模板没有包含System.Text.Json（现在新模板一般都自带了），也可以确认一下，它是我们处理JSON序列化的核心。

1.2 获取模型服务配置

要调用文墨共鸣的服务，你需要有相应的访问凭证。这通常包括：

API Base Url：服务的基础地址，比如https://api.example.com/v1。
API Key：用于身份验证的密钥。

这些信息一般在你申请使用服务后，由服务提供商提供。千万不要把这些敏感信息硬编码在代码里！接下来我们就把它放到安全的地方。

1.3 配置模型服务参数

在appsettings.json文件里，添加一个配置节来存放这些信息。这样以后要修改或者区分开发、生产环境就非常方便。

{ "Logging": { ... }, "AllowedHosts": "*", "AiModelService": { "BaseUrl": "YOUR_API_BASE_URL_HERE", "ApiKey": "YOUR_API_KEY_HERE", "ModelName": "wenmo-resonance", // 或其他具体模型名称 "TimeoutSeconds": 30 } }

配置好了，怎么在代码里用呢？我们用一个简单的类来映射这些配置。

2. 核心服务层设计与实现

这部分是重头戏，我们要设计一个健壮的服务层来处理所有与大模型的通信逻辑。

2.1 定义配置与请求响应模型

先创建一个AiModelOptions.cs类，用来强类型地读取配置：

namespace AILanguageService.Configs { public class AiModelOptions { public const string SectionName = "AiModelService"; public string BaseUrl { get; set; } = string.Empty; public string ApiKey { get; set; } = string.Empty; public string ModelName { get; set; } = string.Empty; public int TimeoutSeconds { get; set; } = 30; } }

接着，定义我们调用模型时发送的请求体。这需要根据文墨共鸣API的实际要求来定，一个典型的对话请求可能长这样：

namespace AILanguageService.Models.Requests { public class ChatCompletionRequest { public string Model { get; set; } = string.Empty; public List<Message> Messages { get; set; } = new(); public bool Stream { get; set; } = false; // 其他可选参数，如 Temperature, MaxTokens等 public float? Temperature { get; set; } public int? MaxTokens { get; set; } } public class Message { public string Role { get; set; } = string.Empty; // "system", "user", "assistant" public string Content { get; set; } = string.Empty; } }

然后，定义API返回的响应模型。对于流式和非流式响应，结构可能不同。

namespace AILanguageService.Models.Responses { // 非流式响应 public class ChatCompletionResponse { public string Id { get; set; } = string.Empty; public List<Choice> Choices { get; set; } = new(); // ... 其他字段 } public class Choice { public Message Message { get; set; } = new(); // ... 其他字段 } // 流式响应块 (Server-Sent Events 格式) public class ChatCompletionStreamResponse { public string Id { get; set; } = string.Empty; public List<StreamChoice> Choices { get; set; } = new(); } public class StreamChoice { public Delta Delta { get; set; } = new(); } public class Delta { public string Content { get; set; } = string.Empty; } }

2.2 实现HTTP客户端服务

这是核心中的核心。我们创建一个AiModelService.cs，利用HttpClientFactory来发送请求。

using System.Net.Http.Headers; using System.Text; using System.Text.Json; using AILanguageService.Configs; using AILanguageService.Models.Requests; using AILanguageService.Models.Responses; using Microsoft.Extensions.Options; namespace AILanguageService.Services { public interface IAiModelService { Task<ChatCompletionResponse> GetChatCompletionAsync(ChatCompletionRequest request, CancellationToken ct = default); IAsyncEnumerable<string> StreamChatCompletionAsync(ChatCompletionRequest request, CancellationToken ct = default); } public class AiModelService : IAiModelService { private readonly HttpClient _httpClient; private readonly AiModelOptions _options; private readonly JsonSerializerOptions _jsonOptions; private readonly ILogger<AiModelService> _logger; public AiModelService(HttpClient httpClient, IOptions<AiModelOptions> options, ILogger<AiModelService> logger) { _httpClient = httpClient; _options = options.Value; _logger = logger; // 配置HttpClient _httpClient.BaseAddress = new Uri(_options.BaseUrl); _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _options.ApiKey); _httpClient.Timeout = TimeSpan.FromSeconds(_options.TimeoutSeconds); _jsonOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }; } public async Task<ChatCompletionResponse> GetChatCompletionAsync(ChatCompletionRequest request, CancellationToken ct = default) { // 确保使用配置中的模型名 request.Model = _options.ModelName; var jsonContent = JsonSerializer.Serialize(request, _jsonOptions); using var httpContent = new StringContent(jsonContent, Encoding.UTF8, "application/json"); try { var response = await _httpClient.PostAsync("chat/completions", httpContent, ct); response.EnsureSuccessStatusCode(); var responseJson = await response.Content.ReadAsStringAsync(ct); var result = JsonSerializer.Deserialize<ChatCompletionResponse>(responseJson, _jsonOptions); return result ?? throw new InvalidOperationException("Failed to deserialize response."); } catch (HttpRequestException ex) { _logger.LogError(ex, "HTTP request failed during chat completion."); throw new ServiceException("AI model service request failed.", ex); } } // 流式响应方法在下一节详细展开 public async IAsyncEnumerable<string> StreamChatCompletionAsync(ChatCompletionRequest request, [EnumeratorCancellation] CancellationToken ct = default) { // 先留个空，下面专门讲 yield break; } } public class ServiceException : Exception { public ServiceException(string message, Exception innerException) : base(message, innerException) { } } }

这里有几个关键点：

依赖注入：通过构造函数注入配置好的HttpClient、IOptions<AiModelOptions>和ILogger。
集中配置：在构造函数中一次性配置HttpClient的基地址、认证头和超时时间。
错误处理：捕获HttpRequestException，记录日志并抛出自定义的业务异常，方便上层统一处理。
JSON序列化：使用System.Text.Json并统一命名策略为驼峰式，确保与大多数API兼容。

2.3 实现异步流式响应

让API像ChatGPT一样一个字一个字地返回，体验会好很多。这依赖于服务端发送事件（Server-Sent Events, SSE）技术。在.NET中，我们可以用IAsyncEnumerable<string>来优雅地实现。

更新上面的StreamChatCompletionAsync方法：

public async IAsyncEnumerable<string> StreamChatCompletionAsync(ChatCompletionRequest request, [EnumeratorCancellation] CancellationToken ct = default) { request.Model = _options.ModelName; request.Stream = true; // 关键：开启流式 var jsonContent = JsonSerializer.Serialize(request, _jsonOptions); using var httpContent = new StringContent(jsonContent, Encoding.UTF8, "application/json"); using var response = await _httpClient.PostAsync("chat/completions", httpContent, HttpCompletionOption.ResponseHeadersRead, ct); response.EnsureSuccessStatusCode(); using var stream = await response.Content.ReadAsStreamAsync(ct); using var reader = new StreamReader(stream); while (!reader.EndOfStream && !ct.IsCancellationRequested) { var line = await reader.ReadLineAsync(ct); if (string.IsNullOrEmpty(line) || !line.StartsWith("data: ")) { continue; } var eventData = line["data: ".Length..]; if (eventData == "[DONE]") { yield break; // 流结束 } try { var streamBlock = JsonSerializer.Deserialize<ChatCompletionStreamResponse>(eventData, _jsonOptions); var content = streamBlock?.Choices?.FirstOrDefault()?.Delta?.Content; if (!string.IsNullOrEmpty(content)) { yield return content; } } catch (JsonException ex) { _logger.LogWarning(ex, "Failed to deserialize a stream block: {Data}", eventData); // 可以选择忽略单个错误块，继续读取 } } }

这个方法做了几件事：

设置request.Stream = true，告诉API我们需要流式响应。
使用HttpCompletionOption.ResponseHeadersRead，使得请求一收到响应头就开始读取流，而不是等整个响应体下载完。
逐行读取响应流，识别SSE格式的data:前缀。
解析每一块JSON数据，提取出content字段并yield return出去。
遇到[DONE]事件或流结束，则终止枚举。

3. 配置依赖注入与控制器封装

服务写好了，怎么让它跑起来呢？需要在Program.cs（或Startup.cs）里进行配置。

3.1 注册服务与配置

打开Program.cs文件，添加以下代码：

using AILanguageService.Configs; using AILanguageService.Services; var builder = WebApplication.CreateBuilder(args); // 添加服务到容器 builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); // 可选，方便API测试 // 1. 配置AiModelOptions builder.Services.Configure<AiModelOptions>( builder.Configuration.GetSection(AiModelOptions.SectionName)); // 2. 配置命名的HttpClient，并将其生命周期设置为Transient或Scoped builder.Services.AddHttpClient<IAiModelService, AiModelService>() .ConfigureHttpClient((serviceProvider, client) => { // 配置已在AiModelService构造函数中完成，此处可进行额外全局配置 // 例如：client.DefaultRequestHeaders.Add("User-Agent", "MyAIService"); }) .SetHandlerLifetime(TimeSpan.FromMinutes(5)); // 设置Handler生命周期 // 3. 注册业务服务（AddHttpClient已经注册了AiModelService，这里通常不需要再单独AddScoped） // builder.Services.AddScoped<IAiModelService, AiModelService>(); // 通常不需要 var app = builder.Build(); // 配置HTTP请求管道 if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();

通过AddHttpClient<IAiModelService, AiModelService>()，我们完成了两件事：注册了IAiModelService及其实现，并为这个实现配置了一个专用的HttpClient实例。

3.2 创建API控制器

现在，创建一个Web API控制器来暴露给前端调用。我们设计两个端点：一个用于普通响应，一个用于流式响应。

using AILanguageService.Models.Requests; using AILanguageService.Services; using Microsoft.AspNetCore.Mvc; namespace AILanguageService.Controllers { [ApiController] [Route("api/[controller]")] public class ChatController : ControllerBase { private readonly IAiModelService _aiModelService; private readonly ILogger<ChatController> _logger; public ChatController(IAiModelService aiModelService, ILogger<ChatController> logger) { _aiModelService = aiModelService; _logger = logger; } [HttpPost("completion")] public async Task<IActionResult> GetCompletion([FromBody] ChatCompletionRequest request) { if (request == null || !request.Messages.Any()) { return BadRequest("Request or messages cannot be empty."); } try { var response = await _aiModelService.GetChatCompletionAsync(request); return Ok(response); } catch (ServiceException ex) { _logger.LogError(ex, "Error getting chat completion."); return StatusCode(502, "Upstream service error."); // Bad Gateway } catch (Exception ex) { _logger.LogError(ex, "Unexpected error in chat completion."); return StatusCode(500, "Internal server error."); } } [HttpPost("completion/stream")] public async Task StreamCompletion([FromBody] ChatCompletionRequest request, CancellationToken ct) { if (request == null || !request.Messages.Any()) { Response.StatusCode = 400; await Response.WriteAsync("Request or messages cannot be empty.", ct); return; } Response.ContentType = "text/event-stream"; Response.Headers.CacheControl = "no-cache"; Response.Headers.Connection = "keep-alive"; try { await foreach (var chunk in _aiModelService.StreamChatCompletionAsync(request, ct).WithCancellation(ct)) { // 按照SSE格式返回：`data: {chunk}\n\n` var sseData = $"data: {JsonSerializer.Serialize(new { content = chunk })}\n\n"; await Response.WriteAsync(sseData, ct); await Response.Body.FlushAsync(ct); // 立即刷新，确保数据发送到客户端 } // 发送结束标记 await Response.WriteAsync("data: [DONE]\n\n", ct); await Response.Body.FlushAsync(ct); } catch (OperationCanceledException) { _logger.LogInformation("Streaming was cancelled by the client."); } catch (Exception ex) { _logger.LogError(ex, "Error during streaming chat completion."); // 可以尝试发送一个错误事件，但连接可能已中断 } } } }

流式端点特别注意：

ContentType设置为text/event-stream。
使用Response.Body.FlushAsync()确保数据块立即发送，而不是缓冲。
妥善处理CancellationToken，以便在客户端断开连接时能及时取消。

4. 运行测试与进阶技巧

代码写完了，我们来试试看效果如何。

4.1 运行与测试项目

在项目根目录下，运行：

dotnet run

或者直接在IDE里启动。应用启动后，通常会打开Swagger页面（如果你配置了的话），地址是https://localhost:xxxx/swagger。

测试普通接口 (/api/chat/completion)：在Swagger UI或Postman中，发送一个POST请求：

{ "messages": [ { "role": "user", "content": "用一句话介绍.NET" } ] }

你应该会收到一个完整的JSON响应。

测试流式接口 (/api/chat/completion/stream)：这个不能用普通的Swagger UI测试，需要使用支持SSE的客户端。你可以用curl命令：

curl -X POST https://localhost:xxxx/api/chat/completion/stream \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"用一句话介绍.NET"}]}' \ -N

或者写一个简单的前端HTML页面，使用EventSourceAPI来接收数据。看到文字一个一个地“流”回来，感觉就对了。

4.2 进阶优化与建议

在实际项目中，你可能还需要考虑以下几点：

重试与熔断：网络请求可能失败。可以使用Polly这样的库，为HttpClient添加重试、超时和熔断策略。

builder.Services.AddHttpClient<IAiModelService, AiModelService>() .AddTransientHttpErrorPolicy(policy => policy.WaitAndRetryAsync(3, _ => TimeSpan.FromSeconds(2))) .AddPolicyHandler(Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10)));

响应模型统一封装：为前端提供更统一的响应格式，比如包含code、message、data的标准结构。可以在控制器里封装，也可以用中间件统一处理。
请求限流与配额管理：如果调用的是付费API，需要在服务层或中间件里加入请求频率和配额的控制，避免意外超支。
更完善的错误处理：区分不同的错误类型（如认证失败、额度不足、模型不可用等），并返回更精确的HTTP状态码和错误信息。
日志与监控：记录详细的请求和响应日志（注意脱敏API Key），并集成到APM（如Application Insights）中监控服务的健康度和性能。