ModelScope.Net.Runtime.Python 0.1.0-preview.1

ModelScope.Net

ModelScope.Net 是面向 .NET 10 的 ModelScope Hub 与模型运行时迁移项目。当前处于技术预览阶段：Hub 的公开模型查询、校验下载、断点续传、过滤、缓存和离线复用已经可用；Remote API、Python gRPC Worker，以及 BGE 与 all-MiniLM Embedding、DistilBERT SST-2 文本分类和 MobileNet V2 图像分类的 ONNX 路径已经验收；Qwen2.5 0.5B GGUF 已在固定 llama.cpp b10516 上通过 macOS ARM64/CPU 的真实加载、非流式与流式生成、崩溃恢复认证。P5 扩展还完成了固定 SmolLM ONNX 的贪心文本生成本机认证。阶段 3 的 5 个固定 Revision 模型已通过统一技术认证和两轮 CPU 性能门禁；其他平台和模型仍按迁移进度表逐步认证，不能视为 1.0 兼容承诺。

快速开始

dotnet restore ModelScope.Net.sln
dotnet build ModelScope.Net.sln --no-restore
dotnet test ModelScope.Net.sln --no-build

查询和下载公开模型：

dotnet run --project src/ModelScope.Net.Cli -- info Qwen/Qwen2.5-0.5B-Instruct

dotnet run --project src/ModelScope.Net.Cli -- download Qwen/Qwen2.5-0.5B-Instruct \
  --local-dir ./models/qwen \
  --allow "*.json,tokenizer*"

dotnet run --project src/ModelScope.Net.Cli -- inspect ./models/qwen

dotnet run --project src/ModelScope.Net.Cli -- cache verify --cache ~/.cache/modelscope.net

对已下载目录做本地推理（inspect 后由 RuntimeRouter 选择 ONNX / GGUF / Python）：

dotnet run --project src/ModelScope.Net.Cli -- run ./models/qwen \
  --prompt "用一句话介绍 ModelScope"

dotnet run --project src/ModelScope.Net.Cli -- run ./models/bge \
  --runtime onnx-embedding \
  --prompt "a test sentence"

dotnet run --project src/ModelScope.Net.Cli -- run ./models/smollm-135m \
  --runtime onnx-text-generation \
  --task text-generation \
  --payload '{"prompt":"Once upon a time","maxNewTokens":8}'

GGUF 需要已启动的 llama-server，或由 CLI 拉起固定分发：

dotnet run --project src/ModelScope.Net.Cli -- run ./models/qwen-gguf \
  --runtime gguf \
  --llama-server ./artifacts/llama.cpp/llama-b10516/llama-server \
  --prompt "用一句话介绍 ModelScope"

Python Worker 可由 CLI 拉起（--runtime python 或 --python-worker），ONNX 加载失败时开发模式会降级到 Python：

dotnet run --project src/ModelScope.Net.Cli -- run ./models/pipeline-model \
  --runtime python \
  --python-backend modelscope \
  --payload '{"text":"hello"}'

已有隔离端点时继续用 --python-endpoint。需要执行仓库代码时显式加 --allow-remote-code，Worker 会把它映射为 ModelScope trust_remote_code。

调用支持 API Inference 的模型（owner/name 且没有本地目录时走 Remote）：

export MODELSCOPE_API_TOKEN="<token>"
dotnet run --project src/ModelScope.Net.Cli -- run Qwen/Qwen3.5-35B-A3B \
  --runtime remote \
  --task chat \
  --prompt "用一句话介绍 ModelScope" \
  --stream

如需持久化开发环境 Token，可执行 login；Unix 下凭据文件使用 0600 权限。服务器和容器环境仍建议直接注入 Secret。

API Inference 需要账号 Token 且有动态配额。生产系统应显式配置超时、重试与降级，不应假定所有模型都支持远程调用。

当前交付结构

• ModelScope.Net.Abstractions：公共 DTO、能力状态与统一运行时接口。
• ModelScope.Net.Hub：ModelScope 元数据、文件与快照下载客户端。
• ModelScope.Net.Runtime：模型检测、运行时路由，以及 Session 预热、LRU、并发门禁和配额治理。
• ModelScope.Net.Runtime.Remote：OpenAI 兼容 API Inference 适配器。
• ModelScope.Net.Runtime.Python：受控 Python gRPC Worker 客户端、服务端协议、回环鉴权、模型根目录和进程恢复。
• ModelScope.Net.Runtime.Onnx：ONNX Runtime CPU 执行器、原始张量协议、Embedding、文本生成、文本分类与图像分类适配器。
• ModelScope.Net.Runtime.Gguf：GGUF Header/元数据解析、预览白名单、llama-server 受控进程、OpenAI/SSE 调用与崩溃恢复。
• ModelScope.Net.AspNetCore：依赖注入入口，并提供 OpenTelemetry ActivitySource/Meter 和默认安全审计；不记录提示词、Token、输出或异常正文。
• ModelScope.Net.Cli：info、download、inspect、run 和 progress。
• ModelScope.Net.PerformanceBenchmark：固定 Revision 模型的重复 CPU 基准、阈值判定和机器可读证据生成。

8 个库项目可生成版本对齐的 0.1.0-preview.1 本地 NuGet/符号包；CLI、示例、测试及认证工具不进入包集合。生成、验证和发布边界见 NuGet 技术预览分发，版本与模型的联动升级见 升级与回退手册。这不是已公开发布的 1.0 声明。

迁移状态、恢复步骤和验收证据以 迁移进度表 为准；性能结论与容量边界见 P3-08 性能与容量基线，运行时资源控制见 P4-04 模型资源治理，架构边界见 技术方案，阶段计划见 迁移计划。