XY.AI.SemanticKernel 2.0.8

.NET 6.0 .NET Standard 2.0 .NET Framework 4.8

There is a newer version of this package available.
See the version list below for details.

dotnet add package XY.AI.SemanticKernel --version 2.0.8

NuGet\Install-Package XY.AI.SemanticKernel -Version 2.0.8

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="XY.AI.SemanticKernel" Version="2.0.8" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="XY.AI.SemanticKernel" Version="2.0.8" />
                    

                            Directory.Packages.props

<PackageReference Include="XY.AI.SemanticKernel" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add XY.AI.SemanticKernel --version 2.0.8

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: XY.AI.SemanticKernel, 2.0.8"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package XY.AI.SemanticKernel@2.0.8

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=XY.AI.SemanticKernel&version=2.0.8
                    

                            Install as a Cake Addin

#tool nuget:?package=XY.AI.SemanticKernel&version=2.0.8
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

XY.AI.SemanticKernel

基于 Microsoft.SemanticKernel 的结构化数据提取帮助类库。

功能

提供与参考类相似的 ExtractDataAsync<T> 接口（自定义提示词 / 默认提示词）
抽离 AI 连接参数（模型、Key、Endpoint）到底层 Kernel 注册过程
通过扩展方法直接注册到 .NET DI 容器

适用场景

需要从自然语言中提取结构化 DTO
希望统一通过配置切换 Azure OpenAI / 千问 / DeepSeek
希望在 ASP.NET Core 中通过 DI 直接注入使用

快速使用

using Microsoft.SemanticKernel;
using Microsoft.Extensions.DependencyInjection;
using XY.AI.SemanticKernel;

var services = new ServiceCollection();

var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAIChatCompletion("gpt-4o-mini", "your-api-key");
services.AddSingleton(kernelBuilder.Build());

services.AddXYAIStructuredDataExtractor(options =>
{
    options.SystemPrompt = "你是一个严格输出 JSON 的助手";
});

var sp = services.BuildServiceProvider();
var extractor = sp.GetRequiredService<IAIStructuredDataExtractor>();

var dto = await extractor.ExtractDataAsync<MyDto>("文本内容");

说明：ExtractDataAsync<T> 会要求模型只输出 JSON，并自动清理 ```json 代码块标记后再反序列化。

配置文件说明（推荐）

你可以在 appsettings.json 中同时配置：

AIServices：多模型服务配置
XYAIStructuredData：结构化提取行为配置
XYAIOpenAI：仅使用 OpenAI 一站式注册时的简化配置

完整示例：

{
  "AIServices": {
    "DefaultUseServiceId": "AzureOpenAI",
    "AzureOpenAI": {
      "ModelId": "gpt-4o",
      "Endpoint": "https://weilan.openai.azure.com/",
      "ApiKey": "*****",
      "ServiceId": "AzureOpenAI"
    },
    "QWenPlus": {
      "ModelId": "qwen-plus",
      "Endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "ApiKey": "sk-*****",
      "ServiceId": "QWenPlusAI"
    },
    "DeepSeek": {
      "ModelId": "deepseek-chat",
      "Endpoint": "https://api.deepseek.com/v1",
      "ApiKey": "sk-*****",
      "ServiceId": "DeepSeekChatAI"
    }
  },
  "XYAIStructuredData": {
    "SystemPrompt": "你是一个结构化信息提取助手，只返回 JSON",
    "PropertyNameCaseInsensitive": true
  },
  "XYAIOpenAI": {
    "ModelId": "gpt-4o-mini",
    "ApiKey": "your-api-key"
  }
}

字段说明：

DefaultUseServiceId：多服务同时注册时的默认服务标识
ModelId：模型名称
Endpoint：服务地址（Azure/QWen/DeepSeek 各自 endpoint）
ApiKey：对应服务密钥
ServiceId：Semantic Kernel 内部服务名，用于多服务区分
SystemPrompt：提取器的系统提示词
PropertyNameCaseInsensitive：JSON 反序列化忽略大小写

一站式 OpenAI 注册

using Microsoft.Extensions.DependencyInjection;
using XY.AI.SemanticKernel;

var services = new ServiceCollection();

services.AddXYAIStructuredDataExtractorWithOpenAI(
    modelId: "gpt-4o-mini",
    apiKey: "your-api-key",
    configure: options =>
    {
        options.SystemPrompt = "你是一个严格输出 JSON 的助手";
    });

也支持从配置读取：

services.AddXYAIStructuredDataExtractorWithOpenAI(configuration);

适用：只接入 OpenAI 或 Azure OpenAI 兼容服务，不需要多服务切换。

按单个服务注册（可选）

当你只希望启用一个服务时，可使用单服务重载：

services.AddXYAIKernelWithAIServices(
    configuration,
    XYAIServiceType.QWenPlus);

或一站式注册（内核 + 结构化提取）：

services.AddXYAIStructuredDataExtractorWithAIServices(
    configuration,
    XYAIServiceType.DeepSeek);

适用：配置里有多个服务，但当前应用只想启用其中一个。

多服务同时注册

// 注册 AzureOpenAI + QWen + DeepSeek
builder.Services.AddXYAIKernelWithAIServices(builder.Configuration);

// 再注册结构化提取器
builder.Services.AddXYAIStructuredDataExtractor(builder.Configuration);

或一行完成：

builder.Services.AddXYAIStructuredDataExtractorWithAIServices(builder.Configuration);

接口注册方法总览

AddXYAIStructuredDataExtractor(Action<XYAIStructuredDataOptions>?)
AddXYAIStructuredDataExtractor(IConfiguration, string sectionName = "XYAIStructuredData")
AddXYAIStructuredDataExtractorWithOpenAI(string modelId, string apiKey, Action<XYAIStructuredDataOptions>?)
AddXYAIStructuredDataExtractorWithOpenAI(IConfiguration, string openAISectionName = "XYAIOpenAI", string extractorSectionName = "XYAIStructuredData")
AddXYAIKernelWithAIServices(IConfiguration, string aiServicesSectionName = "AIServices")
AddXYAIKernelWithAIServices(IConfiguration, XYAIServiceType, string aiServicesSectionName = "AIServices")
AddXYAIStructuredDataExtractorWithAIServices(IConfiguration, string aiServicesSectionName = "AIServices", string extractorSectionName = "XYAIStructuredData")
AddXYAIStructuredDataExtractorWithAIServices(IConfiguration, XYAIServiceType, string aiServicesSectionName = "AIServices", string extractorSectionName = "XYAIStructuredData")

使用示例（业务代码）

public sealed class ResumeAppService
{
    private readonly IAIStructuredDataExtractor _extractor;

    public ResumeAppService(IAIStructuredDataExtractor extractor)
    {
        _extractor = extractor;
    }

    public Task<CandidateDto?> ParseAsync(string resumeText, CancellationToken ct)
    {
        return _extractor.ExtractDataAsync<CandidateDto>(resumeText, cancellationToken: ct);
    }
}

自定义 prompt：

var result = await extractor.ExtractDataAsync<OrderDto>(
    text: input,
    prompt: "请提取订单号、金额、下单时间，严格返回 JSON",
    cancellationToken: ct);

Program.cs 推荐注册模板

// 场景 A：多服务同时注册 + 提取器
builder.Services.AddXYAIStructuredDataExtractorWithAIServices(builder.Configuration);

// 场景 B：只启用某一个服务 + 提取器
// builder.Services.AddXYAIStructuredDataExtractorWithAIServices(builder.Configuration, XYAIServiceType.QWenPlus);

// 场景 C：只用 OpenAI 简化注册
// builder.Services.AddXYAIStructuredDataExtractorWithOpenAI(builder.Configuration);

安全建议

不要把 ApiKey 提交到仓库
建议使用环境变量、用户机密、Key Vault 等方式注入密钥

包版本管理（CPM）

本仓库已对 AI 相关项目启用 Directory.Packages.props 中央包版本管理。

版本集中在仓库根目录：Directory.Packages.props
项目文件中的 PackageReference 不再写 Version

如需升级 SK / Extensions，只需修改 Directory.Packages.props。

发布前一键检查

在 XY.AI.SemanticKernel 目录提供了两个脚本：

PowerShell：build.ps1
CMD：build.cmd

执行内容：restore -> build -> test -> pack

示例：

pwsh ./build.ps1 -Configuration Release

产物输出目录：artifacts/packages

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 was computed.
.NET Framework	net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 is compatible. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETFramework 4.8
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Options (>= 10.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.7)
- Microsoft.SemanticKernel (>= 1.74.0)
- Microsoft.SemanticKernel.Connectors.OpenAI (>= 1.74.0)
.NETStandard 2.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Options (>= 10.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.7)
- Microsoft.SemanticKernel (>= 1.74.0)
- Microsoft.SemanticKernel.Connectors.OpenAI (>= 1.74.0)
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Options (>= 10.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.7)
- Microsoft.SemanticKernel (>= 1.74.0)
- Microsoft.SemanticKernel.Connectors.OpenAI (>= 1.74.0)
net6.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Options (>= 10.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.7)
- Microsoft.SemanticKernel (>= 1.74.0)
- Microsoft.SemanticKernel.Connectors.OpenAI (>= 1.74.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
2.0.9	33	5/5/2026
2.0.8	95	4/27/2026
2.0.7	92	4/25/2026
2.0.6	90	4/23/2026
2.0.5	103	4/22/2026
1.0.0	90	4/22/2026

[新增] Added
     - 增补 AI 结构化提取能力说明与 OpenAI 连接器说明。
     [优化] Improved
     - 统一 NuGet 元数据格式（Description/Tags/README/Icon/License/Repository）。
     [修复] Fixed
     - 修正发布说明与版本信息一致性，优化包检索呈现。