Senparc.Xncf.AIKernel 0.17.4

Prefix Reserved
dotnet add package Senparc.Xncf.AIKernel --version 0.17.4
                    
NuGet\Install-Package Senparc.Xncf.AIKernel -Version 0.17.4
                    
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="Senparc.Xncf.AIKernel" Version="0.17.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Senparc.Xncf.AIKernel" Version="0.17.4" />
                    
Directory.Packages.props
<PackageReference Include="Senparc.Xncf.AIKernel" />
                    
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 Senparc.Xncf.AIKernel --version 0.17.4
                    
#r "nuget: Senparc.Xncf.AIKernel, 0.17.4"
                    
#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 Senparc.Xncf.AIKernel@0.17.4
                    
#: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=Senparc.Xncf.AIKernel&version=0.17.4
                    
Install as a Cake Addin
#tool nuget:?package=Senparc.Xncf.AIKernel&version=0.17.4
                    
Install as a Cake Tool

Senparc.Xncf.AIKernel

Senparc.Xncf.AIKernel is the NCF AI model and vector configuration module. It provides persistence, administration services, and integration helpers for Senparc AI model settings.

Features

  • Manages AIModel and AIVector records and their DTO/request models.
  • Provides model and vector application services with paging, create, edit, and delete operations.
  • Builds SenparcAiSetting values and runs model requests through the configured Senparc AI runtime.
  • Monitors AI token usage with real-time in-process aggregation (AITokenMonitorService) and persistent, queryable usage records (AITokenUsageService).
  • Separates real-time token totals and run-progress buffers by the resolved tenant; monitor endpoints read only the current tenant's partition.
  • Publishes per-run token progress as asynchronous events consumable via IAsyncEnumerable (SubscribeAsync), with buffered replay for late subscribers.
  • Surfaces token usage on the AI model list page: overview cards (total tokens / calls / success-error / average duration), per-model usage columns (calls, total tokens with relative bar, last used), alias search, and a shortcut to the Token Monitor page.
  • Synchronizes model metadata from NeuChar services when explicitly requested.
  • Provides an administrator-only local fine-tuning console with validated JSONL datasets, worker preflight, durable jobs, loss/resource telemetry, cancellation and downloadable adapters.
  • Connects to an independent authenticated Python worker: CPU/CUDA PEFT training in restricted containers, or native Apple Silicon MLX training. Training is disabled until explicitly configured.
  • Supports NCF's multi-database context variants and localized module metadata.

Installation

<PackageReference Include="Senparc.Xncf.AIKernel" Version="0.16.4" />

Key API

  • AIModelService.AddAsync(...), EditAsync(...), and BuildSenparcAiSetting(...) manage model configuration.
  • AIModelService.RunModelsync(...) executes a configured model request.
  • AIModelService.UpdateModelsFromNeuCharAsync(...) refreshes model metadata from NeuChar.
  • AIVectorService.AddAsync(...) and EditAsync(...) manage vector configuration.
  • AITokenMonitorService.Record(...) accumulates per-call token totals (overall / by model / by day) thread-safely; GetLiveStats(...) returns the aggregated AITokenMonitorStats.
  • AITokenMonitorService.PublishProgress(...) and SubscribeAsync(runId, ...) expose asynchronous per-run token progress as an IAsyncEnumerable<AITokenProgressEvent> with buffered replay.
  • AITokenUsageService.RecordAsync(...) and GetStatsAsync(...) persist usage records and compute aggregate statistics; AITokenUsageSnapshot.Normalize() fills a missing total from input + output.
  • AITokenUsageService.GetModelUsageMapAsync(...) returns per-model usage aggregates (via TokenUsageAggregator) used by AIModelAppService to attach AIModelDto.Usage on the model list.
  • AIModelAppService and AIVectorAppService expose NCF function/application endpoints; AIModelStudioAppService is the model-studio integration point.

Testing

Senparc.Xncf.AIKernel.Tests (MSTest) covers token monitoring and the fine-tuning integration:

  • AITokenUsageSnapshotTests - normalization, total fallback, and empty detection.
  • AITokenProgressEventTests - completion-state derivation.
  • AITokenMonitorServiceRecordTests - real-time aggregation (overall / by model / by day), clamping, and concurrency safety.
  • AITokenMonitorServiceProgressTests and AITokenMonitorServiceAsyncProgressTests - buffered replay, live IAsyncEnumerable subscription, multi-subscriber delivery, burst/concurrent delivery, and cancellation.
  • FineTuningWorkerClientTests - AdminOnly policy, private worker authentication, parameter/dataset bounds, cursor telemetry, cancellation, invalid responses and explicit worker failures.
  • FineTuningWorkerPersistenceTests - actual SQLite Worker-profile create/read/update round trips without storing API keys.
  • FineTuningLiveWorkerTests - opt-in named-profile typed-client integration against a disposable CPU worker provisioned with tiny-gpt2; supply NCF_TEST_WORKER_ENDPOINT and NCF_TEST_WORKER_KEY to verify actual training, explicit independent validation, events, archive download, paging and cancellation. Without these variables, this integration test is skipped; the companion native-smoke runner can supply them automatically.
dotnet test src/Extensions/Senparc.Xncf.AIKernel.Tests/Senparc.Xncf.AIKernel.Tests.csproj

Local fine-tuning / 本地模型微调

Open AIKernel → Local fine-tuning after installing the module. Model inference configuration and Token Monitor alone do not train models; this feature runs a separate training worker and does not change existing inference behavior.

模块安装后,打开 AIKernel → 本地模型微调。模型推理配置及 Token 监控本身不提供训练能力;新增功能通过独立 Worker 执行训练,不改变已有推理行为。

The worker source, container images and initialization instructions are in tools/AIKernelFineTuning. Configure the NCF host:

Worker 源码、容器镜像及初始化说明位于 tools/AIKernelFineTuning。在 NCF 宿主中配置:

{
  "SenparcXncfAIKernel": {
    "FineTuning": {
      "Enabled": false,
      "AllowedHosts": [ "127.0.0.1" ],
      "WorkerApiKeys": { "cpu_lab": "" }
    }
  }
}

Set SenparcXncfAIKernel__FineTuning__WorkerApiKeys__cpu_lab through an environment variable/secret store to the same value as the worker's NCF_WORKER_KEY (at least 32 characters). Create a database Worker profile in the UI with alias cpu_lab, endpoint http://127.0.0.1:8091, timeout 180 seconds and enabled state. Enable the global switch only after provisioning the Worker. Legacy WorkerEndpoint/WorkerApiKey settings do not configure these profiles. Never commit real keys. Use private TLS for cross-host connections and do not expose the worker directly to browsers.

通过环境变量或密钥存储设置 SenparcXncfAIKernel__FineTuning__WorkerApiKeys__cpu_lab,与 Worker 的 NCF_WORKER_KEY 一致(至少 32 字符)。在 UI 中创建数据库 Worker 配置:别名 cpu_lab、端点 http://127.0.0.1:8091、超时 180 秒、启用状态。准备好 Worker 后再启用全局开关。旧 WorkerEndpoint/WorkerApiKey 不用于这些配置。不要提交真实密钥;跨主机使用私网 TLS,不要将 Worker 直接暴露给浏览器。

For an existing installation, upgrade the AIKernel module through module management so its database migrations add the Worker profile table. New source changes do not imply a package has already been published.

已有安装需通过模块管理升级 AIKernel,应用数据库迁移以新增 Worker 配置表。源码更新不代表对应包已发布。

The UI opens a five-stage tutorial by default, links to both language guides, offers downloadable four-row JSONL examples, validates dataset structure/limits with line numbers, and explains every advanced parameter. Worker switching clears scoped model/dataset/job selections and rejects stale responses; requests follow the selected profile's timeout. Start with the default 10-step smoke test, then evaluate separately before inference deployment.

UI 默认展开五阶段教程,提供中英文文档入口、四行 JSONL 样例下载、带行号的数据结构/边界校验和全部高级参数解释。切换 Worker 会清空其模型/数据集/任务选择并拒绝旧响应,请求遵循所选配置的超时。先运行默认 10 步冒烟测试,再独立评估后部署推理。

Module pages load _AIKernelLocalizationScripts rather than the Admin host's generic partial, so frontend labels resolve to real localized text. An unconfigured Worker is shown as a guided setup state; actual API failures remain errors. Rebuild/restart the host after updating the module.

模块页面使用专属 _AIKernelLocalizationScripts,避免与 Admin 宿主同名 partial 冲突而显示资源键。尚未配置 Worker 时展示操作引导,真实 API 故障仍显示错误。更新模块后需重新构建并重启宿主。

Functionality is the acceptance criterion, not the appearance of the UI. The backend validates offline models/data, executes real adapter updates/evaluation, persists jobs/events and exports compatible artifacts. The UI consumes Worker 1.1+ paging APIs to expose records beyond the legacy first 100 and uses persistent storeId to invalidate cached resources when storage changes. Legacy array endpoints remain available for existing clients. The global switch blocks NCF access; it does not terminate running Worker children.

验收以功能为中心,不以页面外观代替训练正确性。后端负责离线模型/数据校验、真实适配器更新与验证、任务/事件持久化及兼容产物导出。UI 使用 Worker 1.1+ 分页接口操作超过旧接口最近 100 条的历史,并以持久化 storeId 在存储变化时清空旧资源缓存。旧数组接口保留兼容。全局开关阻断 NCF 接入,并不终止已运行的 Worker 子进程。

NCF upload/create/cancel APIs take the typed JSON DTO as their first parameter and workerAlias from query. The frontend follows that contract and validates profile-save responses as Worker DTOs, not job DTOs. Tests generate the actual dynamic controllers to verify binding; no third-party framework source is patched.

NCF 上传/提交/取消 API 的第一个参数为 JSON DTO,workerAlias 来自 query。前端遵循该契约,并按 Worker DTO 而非任务 DTO 校验配置保存结果。测试实际生成动态 Controller 验证绑定,不修改第三方框架源码。

Verified on 2026-10-07: native CPU LoRA and native MLX LoRA/quantized-LoRA training, evaluation, exports and running/queued cancellation; all three adapters were reloaded for inference with nonzero parameter/output changes. Named-profile .NET live integration and SQLite persistence also passed. This verifies infrastructure, not useful model quality or CUDA hardware.

2026-10-07 已实际验证原生 CPU LoRA、原生 MLX LoRA/量化 LoRA 的训练、验证、导出及运行/排队取消;三种 adapter 均重载推理,确认参数和输出真实变化。命名配置的 .NET 实时集成及 SQLite 持久化也已通过。这证明基础设施,不代表业务模型质量或 CUDA 硬件已验收。

CPU and NVIDIA CUDA training use dedicated fixed-purpose containers, not arbitrary commands in the existing short-lived Sandbox templates. Docker Desktop cannot expose Apple Metal GPUs; MLX runs in a native macOS environment with separate OS permissions. Training outputs are adapters, not automatically published inference models. Evaluate, review and deploy through an appropriate serving runtime before adding an AIModel inference configuration.

CPU 与 NVIDIA CUDA 使用专用固定功能容器,而非在现有短时 Sandbox 模板中执行任意命令。Docker Desktop 无法提供 Apple Metal GPU,MLX 需在独立权限的原生 macOS 环境中运行。训练产物为适配器,不会自动发布为推理模型;应先评估、审核并通过适合的推理运行时部署,再添加 AIModel 配置。

Full bilingual concepts, operating procedures and production guidance are maintained in NcfDocs: English / 中文.

The module stores provider settings and may process prompts or model output. Keep API keys in secure configuration, restrict model administration, and apply tenant/data-retention rules before enabling it for users.

Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on Senparc.Xncf.AIKernel:

Package Downloads
Senparc.Xncf.XncfBuilder

Module description.

Senparc.Xncf.PromptRange

Your Prompt Training Range

Senparc.Xncf.MCP

Model Context Protocol(MCP) Manager

Senparc.Xncf.KnowledgeBase

AI Knowledge Base

Senparc.Xncf.AIAgentsHub

AI Agent Hub Module

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.17.4 54 11/19/2026
0.17.3 162 11/11/2026
0.17.2 105 11/5/2026
0.17.1 154 11/2/2026
0.16.4 123 10/10/2026
0.16.3 128 10/4/2026
0.16.2 154 9/18/2026
0.16.1 137 9/16/2026
0.16.0 128 9/15/2026
0.15.5 205 8/29/2026
0.15.4 336 8/23/2026
0.15.3-preview12 199 8/14/2026
0.15.3-preview10 184 8/12/2026
0.15.2-preview9 188 8/8/2026
0.15.1-preview8 210 8/3/2026
0.15.0-preview7 203 7/31/2026
0.14.1-preview6 181 7/28/2026
0.14.0-preview5 172 7/26/2026
0.13.5-preview4 146 7/15/2026
0.13.4-preview3 118 7/5/2026
Loading failed

[2024-08-06] v0.8.6-preview1 update Senparc.AI.Kernel
       [2024-08-18] v0.8.10 Updated module behavior and related support.
       [2024-08-28] v0.8.9 Updated module behavior and related support.
       v0.1.0 initial release
       v0.1.3 Updated module behavior and related support.
       v0.2.0 Updated module behavior and related support.
       v0.3.0 Updated module behavior and related support.
       v0.3.3 upgrade Senparc.AI, improvemodelinvocation, supportstreamingoutput
       v0.5.2 Updated module behavior and related support.
       v0.5.3.1 Updated module behavior and related support.
       v0.8.3 support Ollama
       [2024-08-28] v0.8.10.6-preview1 Updated module behavior and related support.
       [2024-08-28] v0.8.10.7-preview1 Updated module behavior and related support.
       [2024-08-28] v0.8.10.11-preview1 improve NeuChar AI modelsynchronizeprompt
       [2024-08-31] v0.9.0-preview1 Updated module behavior and related support.
       [2024-09-03] v0.9.1-preview1 Updated module behavior and related support.
       [2024-09-07] v0.9.2-preview1 Updated module behavior and related support.
       [2024-09-10] v0.9.3-preview1 upgrade the cache foundation libraries
       [2024-10-09] v0.9.5-preview1 Updated module behavior and related support.
       [2024-10-16] v0.9.6-preview1 Updated module behavior and related support.
       [2024-11-04] v0.10.0-preview1 Updated module behavior and related support.
       [2024-11-08] v0.10.1-preview1 upgrade Senparc.AI
       [2024-11-15] v0.11.0-preview1 Updated module behavior and related support.
       [2024-11-21] v0.12.2-preview1 Updated module behavior and related support.
       [2024-11-28] v0.12.3-preview1 update CO2NET, use new SenparcSetting with UseLowerCaseApiName property
       [2024-12-27] v0.12.4-preview1 Add exception log for UseXncfModules() auto progress
       [2025-01-25] v0.12.8-preview1 Update Agents functions, support for function calling
       [2025-01-28] v0.12.9-preview1 update Senparc.AI
       [2025-02-06] v0.12.11-preview1 update NeuCharAI model update
       [2025-02-08] v0.12.12-preview1 add optional parameter to RunModelsync
       [2025-02-22] v0.12.13-preview1 add DeepSeek-R1 model option
       [2025-04-29] v0.12.16-preview1 Update CO2NET and AIKernel
       [2025-04-29] v0.12.17-preview1 Update CO2NET and AIKernel
       [2025-05-18] v0.12.18-preview1 Update Installation
       [2025-06-20] v0.12.20-preview Add MCP functions in XncfRegisterBase class
       [2026-03-24] v0.12.24-preview.1 update Senparc.AI.Kernel to v0.28.0
       [2026-04-24] Simplify FunctionRender request parameters and keep SelectionList UI metadata compatibility
       [2026-07-02] v0.13.2-preview1 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-07-05] v0.13.3-preview2 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-07-05] v0.13.4-preview3 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-07-07] v0.13.5-preview4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-07-17] v0.14.0-preview5 Updated module behavior and related support.
       1. integrateshared resource-localization mechanism, supportmodulefeature textdisplay dynamically according to the current culture
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       5. Updated module behavior and related support.
       6. Updated module behavior and related support.
       [2026-07-29] v0.14.1-preview6 Dependency update from Senparc.Ncf.AreaBase to 0.22.0-preview3
       [2026-07-31] v0.15.0-preview7 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-08-04] v0.15.1-preview8 Dependency updates from upstream projects
       1. Dependency update from Senparc.Ncf.AreaBase to 0.23.1-preview5
       2. Dependency update from Senparc.Ncf.DatabasePlant to 0.21.5-preview5
       3. Dependency update from Senparc.Ncf.XncfBase to 0.24.0-preview5
       [2026-08-08] v0.15.2-preview9 Dependency updates from upstream projects
       1. Dependency update from Senparc.Ncf.AreaBase to 0.23.2-preview6
       2. Dependency update from Senparc.Ncf.DatabasePlant to 0.21.6-preview6
       3. Dependency update from Senparc.Ncf.XncfBase to 0.24.1-preview6
       [2026-08-13] v0.15.3-preview10 Dependency update from Senparc.Ncf.AreaBase to 0.23.3-preview7; Senparc.Ncf.DatabasePlant to 0.21.7-preview7; Senparc.Ncf.XncfBase to 0.25.0-preview7
       [2026-08-13] v0.15.3-preview11 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-08-14] v0.15.3-preview12 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-08-17] v0.15.4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-08-29] v0.15.5 Dependency updates from Senparc.Ncf.DatabasePlant to 0.21.10; Dependency update from Senparc.Ncf.XncfBase to 0.26.1
       1. Dependency update from Senparc.Ncf.DatabasePlant to 0.21.10
       2. Dependency update from Senparc.Ncf.XncfBase to 0.26.1
       [2026-09-15] v0.16.0 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-09-16] v0.16.1 adapt Senparc.NeuChar.App 1.6.0 dependency
       1. Updated module behavior and related support.
       [2026-09-17] v0.16.2 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-10-01] v0.16.3 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-10-05] v0.16.3 Merge remote-tracking branch 'origin/Developer-MAF-V3' into Developer-MAF-V3-Spark
       1. Updated Senparc.Xncf.AIKernel project behavior and integration for the latest feature and reliability improvements.
       2. chore: update package versions and dependencies across multiple projects
       [2026-10-06] v0.16.4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-10-07] v0.16.4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-10-09] v0.16.4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       [2026-11-03] v0.17.0 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. adapt Senparc.AI.AgentKernel 0.1.15-preview2
       5. Updated module behavior and related support.
       6. Updated module behavior and related support.
       7. Updated module behavior and related support.
       [2026-11-03] Add localized contextual documentation for fine-tuning Workers and vector storage.
       [2026-11-04] v0.17.2 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Dependency update from Senparc.Ncf.AreaBase to 0.23.10
       4. Dependency update from Senparc.Ncf.DatabasePlant to 0.21.14
       5. Dependency update from Senparc.Ncf.XncfBase to 0.28.2
       [2026-11-11] v0.17.2 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-11-12] v0.17.3 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-11-19] v0.17.4 Localized AI fine-tuning and monitoring surfaces
       1. Updated localized labels, resource fallbacks, and user-facing messages across affected surfaces.
       2. Kept runtime behavior and module integration aligned with the affected service and registration changes.