Bitzsoft.Integrations.AI.AspNetCore 1.0.5

Bitzsoft.Integrations.AI.AspNetCore

面向 ASP.NET Core 宿主的 AI 流式响应协议写出器连接器包。将 Bitzsoft.Integrations.AI.Conversation 产出的 IAsyncEnumerable<AIStreamFrame> 安全写出至 HttpContext，内置 SSE 与 NDJSON 双协议协商、Nginx/网关反向代理防缓冲响应头、UTF-8 中文零转义序列化、客户端主动断连静默收敛与未处理异常强脱敏兜底。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.AspNetCore

• 目标框架：net8.0;net10.0；
• 框架引用：Microsoft.AspNetCore.App（零额外第三方 NuGet 包依赖）；
• 项目依赖：Bitzsoft.Integrations.AI.Conversation。

核心行为契约

1. 双协议内容协商（NegotiateFormat）：
   • 查询参数优先：?format=ndjson 协商为 application/x-ndjson; charset=utf-8（每帧 {json}\n）；?format=sse 协商为 text/event-stream; charset=utf-8（默认每帧 data: {json}\n\n，开启 EmitSseEventField = true 时输出 event: {type}\ndata: {json}\n\n）；
   • 请求头次之：解析 Accept 请求头中 application/x-ndjson 与 text/event-stream 的优先级，缺省回退至 DefaultFormat（默认 SSE）。
2. 反向代理零缓冲响应头：
   • 自动调用 IHttpResponseBodyFeature.DisableBuffering() 关闭传输层响应缓冲；
   • 自动写入 Cache-Control: no-cache, no-transform、X-Accel-Buffering: no 与 Pragma: no-cache，防止 Nginx、云负载均衡或浏览器代理攒批阻塞首字到达时间（TTFT）。
3. 中文与符号零 \uXXXX 转义：
   • 固定使用 JsonNamingPolicy.CamelCase 与 JavaScriptEncoder.UnsafeRelaxedJsonEscaping（无 BOM UTF-8），中文字符以原生 UTF-8 字节直出，显著降低流式带宽并方便前端与抓包排障。
4. 客户端断连与服务端异常严格区分：
   • 自动联动 HttpContext.RequestAborted 与调用方传入的 CancellationToken：当用户关闭页面或前端主动 AbortController.abort() 时，写出器静默干净退出，绝不补写多余的 error 帧；
   • 当上游模型网关超时（非客户端触发的 TaskCanceledException / TimeoutException）或服务端抛出未处理异常时，真实堆栈仅写入服务端 ILogger，向客户端下发经过敏感路径、密钥字面量与堆栈正则二次清洗的终端 AIStreamFrame.Error（附带 traceId 供运维关联排障）。

完整最小示例

以下示例演示在 ASP.NET Core 请求上下文中注入 IAIStreamResponseWriter 并按协商的 NDJSON 格式实时写出中文流式事件帧：

using System.Text;
using Bitzsoft.Integrations.AI.AspNetCore;
using Bitzsoft.Integrations.AI.Conversation;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddLogging();
services.AddBitzsoftAIStreamWriter();

await using var provider = services.BuildServiceProvider(
    new ServiceProviderOptions { ValidateOnBuild = true, ValidateScopes = true });

var writer = provider.GetRequiredService<IAIStreamResponseWriter>();

var httpContext = new DefaultHttpContext();
httpContext.Request.Headers.Accept = "application/x-ndjson";
using var responseStream = new MemoryStream();
httpContext.Response.Body = responseStream;

static async IAsyncEnumerable<AIStreamFrame> ProduceFramesAsync()
{
    yield return AIStreamFrame.Start(conversationId: "conv-1001", requestId: "req-01", modelId: "qwen-max");
    yield return AIStreamFrame.Message("已完成合同条款比对，未发现高风险冲突。");
    yield return AIStreamFrame.Done(conversationId: "conv-1001", requestId: "req-01", latencyMs: 128);
    await Task.CompletedTask;
}

await writer.WriteFramesAsync(httpContext, ProduceFramesAsync());

string output = Encoding.UTF8.GetString(responseStream.ToArray());
Console.WriteLine($"协商类型：{httpContext.Response.ContentType}，输出帧行数：{output.Split('\n', StringSplitOptions.RemoveEmptyEntries).Length}");