Bitzsoft.Integrations.AI.Conversation 1.0.6

Bitzsoft.Integrations.AI.Conversation

面向企业多租户 AI 对话应用的零 ORM 依赖、零业务词汇会话协议与运行时编排包。统一封装富消息分片与确定性 JSON 落盘预算、前后端流式事件帧协议、推理模型采样防踩坑选项工厂、跨任意分块的思考标签拆分与五维多轮 Token 去重累加投影器、两阶段上下文预算器、非阻断数字事实对账器、幂等请求四态台账与会话互斥租约协调器以及无锁 19 位单调递增主键生成器。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.Conversation

• 目标框架：net8.0;net10.0；
• 项目依赖：Bitzsoft.Integrations.AI.Governance、Bitzsoft.Integrations.AI.Skills；
• 第三方依赖：仅复用 Microsoft.Extensions.AI.Abstractions、DI、Options、Logging，零新增第三方 NuGet 包；
• 不依赖 SqlSugar、EntityFrameworkCore、StackExchange.Redis 或 ASP.NET Core Web 框架（HTTP 写出独立位于 Bitzsoft.Integrations.AI.AspNetCore）。

核心模块与设计边界

双宿主流式事件帧对照表

IAIRequestLedgerStore 双 ORM（SqlSugar / EF Core）实现走查

建议在宿主请求台账表建立 (TenantId, SessionId, RequestId) 唯一索引，并在会话租约表建立 (TenantId, SessionId) 主键或唯一索引（或直接使用 Redis SET NX PX + Lua 释放）：

1. 原子插入或回查（CreateOrGetExistingAsync）：直接尝试插入 Version = 1, Status = Pending 新行；若命中唯一索引冲突异常，立即按 (TenantId, SessionId, RequestId) 回查既有行并返回 new AIRequestLedgerCreateResult(CreatedNew: false, existing)。
2. 双条件乐观并发跃迁（TryTransitionAsync）：
   • SqlSugar 宿主：使用 db.CopyNew().Updateable<SysAiRequestLedger>() 并在 WHERE 子句严格限定 TenantId == tenantId && SessionId == sessionId && RequestId == requestId && Status == (int)expectedStatus && Version == expectedVersion，同时将 Version 更新为 expectedVersion + 1、UpdatedAt 更新为 transition.TransitionedAt，仅当受影响行数 == 1 时返回 true；
   • EF Core 宿主：查询侧统一加 .AsNoTracking()，更新侧使用 ExecuteUpdateAsync 在单条 SQL 内匹配 Status == expectedStatus && Version == expectedVersion 并原子递增 Version。
3. 契约测试基类验收：宿主测试项目直接继承 Bitzsoft.Integrations.AI.Conversation.Testing.AIRequestLedgerStoreContractTestsBase 调用 RunAllContractAssertionsAsync()，一行代码自动验证唯一键幂等、多租户与跨会话隔离、16 路并发抢占单赢家、心跳续期版本保护、会话租约令牌防伪释放与过期自动接管。

完整最小示例

以下示例演示单调 19 位主键生成、推理模型安全选项构建、跨块 <think> 流式投影与数字事实对账以及幂等请求抢占与重放：

using Bitzsoft.Integrations.AI.Conversation;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddBitzsoftAIConversation();
services.AddInMemoryBitzsoftAIConversationStores();

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

using var scope = provider.CreateScope();
var idGenerator = scope.ServiceProvider.GetRequiredService<AISequentialIdGenerator>();
var coordinator = scope.ServiceProvider.GetRequiredService<IAIMessageRequestCoordinator>();
var projector = scope.ServiceProvider.GetRequiredService<AIChatResponseProjector>();

// 1. 构建推理模型选项：自动清空不兼容的 Temperature / TopP 并注入 reasoning_effort。
ChatOptions chatOptions = AIChatOptionsFactory.Create(new AIChatSessionRequest
{
    ModelId = "deepseek-reasoner",
    IsReasoningModel = true,
    ReasoningEffort = "high",
    Temperature = 0.7f,
    TopP = 0.9f,
});

// 2. 计算确定性请求指纹并声明幂等执行权。
string fingerprint = coordinator.ComputeFingerprint(new AIRequestFingerprintInput(
    TenantId: "tenant-demo",
    UserId: "user-01",
    SessionId: "sess-100",
    Prompt: "汇总本月已审结账单金额"));

var claim = await coordinator.TryClaimOrGetExistingAsync(new AIRequestClaimRequest(
    TenantId: "tenant-demo",
    UserId: "user-01",
    SessionId: "sess-100",
    RequestId: "req-20261107-01",
    RequestFingerprint: fingerprint,
    UserMessageId: idGenerator.NextId()));

if (claim.Outcome == AIRequestClaimOutcome.Acquired && claim.Entry is not null)
{
    // 3. 投影跨分块 <think> 流式更新并执行工具结果数字事实对账。
    static async IAsyncEnumerable<ChatResponseUpdate> MockStreamAsync()
    {
        yield return new ChatResponseUpdate(ChatRole.Assistant, [new FunctionCallContent("call-1", "query_bill_summary")]);
        yield return new ChatResponseUpdate(ChatRole.Tool, [new FunctionResultContent("call-1", """{"totalAmount":1200000}""")]);
        yield return new ChatResponseUpdate(ChatRole.Assistant, "<thi");
        yield return new ChatResponseUpdate(ChatRole.Assistant, "nk>核对账单金额 1200000 元</think>本月已审结总额为 120万元。");
        await Task.CompletedTask;
    }

    await foreach (AIStreamFrame frame in projector.ProjectStreamAsync(
        MockStreamAsync(),
        conversationId: "sess-100",
        requestId: "req-20261107-01",
        modelId: chatOptions.ModelId))
    {
        if (frame.Type == AIStreamFrameTypes.Done)
        {
            string? partsJson = AIMessagePartSerializer.Serialize(projector.Parts);
            await coordinator.MarkCompletedAsync(new AIRequestCompletionUpdate(
                TenantId: "tenant-demo",
                SessionId: "sess-100",
                RequestId: "req-20261107-01",
                ExpectedVersion: claim.Entry.Version,
                AssistantMessageId: idGenerator.NextId(),
                ResponseText: projector.PersistenceContent,
                PartsJson: partsJson,
                Usage: projector.Usage));
        }
    }
}

Console.WriteLine($"正文输出：{projector.AssistantText}，思考参数已清理：{chatOptions.Temperature is null}");