# Tomur

**Repository Path**: IoTSharp/Tomur

## Basic Information

- **Project Name**: Tomur
- **Description**: Tomur 支持用纯 C# 加载本地大模型，实现私密流畅的智能对话；同时另以 llama.cpp 及专用组件提供语音识别、发音、图像生成等多模态能力。
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tomur

[English](./README.en.md)

Tomur 是基于 .NET 10 与 C# 构建的本地 AI 运行时与开发者工作台，面向离线优先、隐私敏感、低运维成本的个人与团队开发环境。单一 `tomur` 进程同时承载 CLI、本地 HTTP 服务、系统服务形态、模型资产管理、运行时诊断和 Chat-first Web 工作台。

Tomur 同时支持两条本地大模型运行路线：由 Tomur 使用纯 C# 实现的托管模型 provider，以及以 llama.cpp 为核心的 native runtime。两条路线并行存在，按模型格式、架构和本机运行条件显式选择。

| 技术路线 | 实现位置 | 能力边界 |
| --- | --- | --- |
| 纯 C# 托管模型 | `providers/Glm`、`providers/Olmoe` | 使用 C# 实现 safetensors 读取、tokenizer、张量与量化 kernel、KV cache、attention、MoE routing、expert cache 和增量生成，不依赖第三方推理 dynamic library。已接通 GLM / MoE 与 OLMoE 的显式模型格式，并取得定向真实模型推理证据；完整协议、性能、资源释放和跨平台矩阵仍按路线图收敛。 |
| llama.cpp native | `native/llama.cpp`、`native/llama.native`、`app/Inference` | 面向 GGUF 文本生成与 embeddings，使用 Tomur 管理的 native bundle、硬件 backend 选择、GPU offload 和 CPU fallback，是当前文本与 embedding 兼容 API 的默认且已有验证路线。 |

两条路线共用同一套模型 Catalog、安装清单、session 管理、OpenAI / Ollama / Anthropic Messages 兼容 API、Runtime 诊断和 Web Chat。模型权重、SQLite 数据库、日志、用户文件和生成结果统一作为本地资产管理。

Web 工作台保持 Chat-first：输入区可发送附件、录制语音回合、选择音频文件仅转写、确认生成本地图片并调整生成参数；会话中的图片、音频、文本附件和生成产物支持预览、打开、下载与复制路径。纯文本、附件或完整语音对话回合重新生成时会替换持久化消息尾部，已生成的本地产物文件继续保留。

## 🧮 纯 C# 大模型运行实证

Tomur 的纯 C# managed provider 已在 Tomur 单进程内完成 GLM-4.7 与 OLMoE 真实模型加载和 Web Chat 非流式对话，不依赖外部推理进程或第三方推理 dynamic library。以下截图记录真实模型回复；证据范围不等同于完整协议、性能与跨平台矩阵均已完成。

**GLM-4.7 Flash REAP 23B A3B** · [验证记录](./docs/r15-glm4-moe-lite-validation.md)

![GLM-4.7 Flash REAP 23B A3B 通过 Tomur 纯 C# provider 完成真实 Web Chat 对话](./docs/images/r15-glm47-web-chat.png)

**OLMoE 1B-7B Instruct int8** · [验证记录](./docs/r15-olmoe-o5-validation.md)

![OLMoE 1B-7B Instruct int8 通过 Tomur 纯 C# provider 完成真实 Web Chat 对话](./docs/images/r15-olmoe-int8-web-chat.png)

## 🧭 为什么是 Tomur

Tomur 不把本地模型能力限定在单一推理后端。纯 C# provider 与 llama.cpp native runtime 在同一个本地程序中使用一致的模型、协议和诊断边界：

1. 🧮 按模型格式和架构在纯 C# GLM / OLMoE provider 与 llama.cpp GGUF runtime 之间显式选择，不用更换服务入口。
2. 🔌 通过同一个本地服务提供 OpenAI、Ollama 和 Anthropic Messages 兼容 API。
3. 📦 在同一个 Catalog 和数据目录中管理模型下载、checksum、安装清单与本地可见性。
4. 💬 使用同一个 Web 工作台直接对话、上传附件并查看实际使用的 provider、runtime 和 session 状态。
5. 🩺 通过 `tomur doctor`、Runtime API 和 UI 诊断托管 provider、native library、模型、内存、端口、代理、SQLite 与硬件状态。
6. 🚀 以自包含、单文件、Native AOT 友好的发布路线降低本地部署前置条件。

Tomur 关注的是本机 AI 运行体验，不是多租户服务器、后台管理平台或复杂工作流治理系统。

## 💬 交流讨论

欢迎加入 Tomur 企业微信群，交流使用体验、本地 AI 实践与项目开发。

<img src="./docs/images/tomur-wecom-group.png" alt="Tomur 企业微信群二维码" width="240">

## 🚀 快速开始

查看命令入口：

```powershell
tomur --help
```

启动本地服务并打开工作台：

```powershell
tomur open
```

准备 native runtime，并安装推荐模型包：

```powershell
tomur native prepare
tomur pull recommended
```

以服务模式运行本地 HTTP API：

```powershell
tomur serve --open
```

源码构建需要 .NET 10 SDK 与 Node.js/npm；主程序会按需执行 `npm ci` 和前端增量构建。开发运行时可直接指向主程序项目：

```powershell
dotnet run --project app -- --help
dotnet run --project app -- serve --open
```

默认本地服务地址为 `http://127.0.0.1:5137`。

## 🧩 目标能力

1. 💬 通过纯 C# provider 与 llama.cpp native runtime 两条路线执行本地文本生成。
2. 🧮 使用 `providers/Glm` 与 `providers/Olmoe` 承载纯 C# GLM / MoE、OLMoE 模型加载、量化、缓存和生成。
3. ⚙️ 使用 llama.cpp 承载 GGUF 文本生成、embeddings、硬件加速选择与 CPU fallback。
4. 🧠 本地 embeddings 与 reranking。
5. 🔌 OpenAI 兼容 HTTP API。
6. 🔁 Ollama 兼容 HTTP API。
7. 🧩 Claude Code 所需的 Anthropic Messages 兼容入口。
8. 📦 模型目录、下载、校验与本地资产管理。
9. 🩺 CPU、内存、磁盘、代理、端口、模型、托管 provider 与 native libraries 运行时诊断。
10. 🎛️ Whisper、OCR native、HyperLPR3 / MNN 车牌识别、stable-diffusion.cpp 与 llama.cpp TTS / GGUF TTS 多模态 native runtime。
11. 🖥️ 系统服务运行模式。
12. 🧑‍💻 React + Ant Design X Web 工作台。
13. 🎙️ 本地 Realtime 语音会话。`tomur.realtime.v1` 已接入一次性 ticket、常驻 Silero/Whisper/TTS、滚动转写、流式文本与短句音频、取消和确认后历史回写；Chat 提供 AudioWorklet 采集播放、设备选择和有界重连。默认半双工，双向模式为要求 AEC 的实验选项；新增 native ABI、构建、真实设备、延迟与发布验收仍待验证，详见 [R20 协议](./docs/r20-realtime-protocol-v1.md)。
14. 🖼️ ONNX 视觉模型提供器（规划中）。参考 `rust-onnx-infer` 的分类、检测、分割、OCR、姿态、人脸、深度、增强、匹配等完整能力矩阵，按 R21 分阶段接入；当前尚未接入或验证，详见 [R21 参考清单](./docs/r21-onnx-vision-provider.md)。

Tomur 不会在未接通本地 runtime 时伪造推理结果。模型缺失、native runtime 或托管 provider 不可用、bundle 资产损坏、上下文超限、能力不匹配或内存不足时，API、CLI 和 UI 都应返回可诊断的错误。

## 🛠️ 工具调用

OpenAI `POST /v1/chat/completions` 与 Ollama `POST /api/chat` 兼容端点支持 function 工具声明、模型返回的 tool calls，以及客户端执行工具后回灌结果的后续消息。兼容端点不会在服务端执行客户端声明的任意函数，工具实现与执行权限仍由客户端负责；OpenAI `strict=true` 当前明确返回 400。

`POST /api/agents/chat` 面向 Tomur 本地工具提供不同的执行边界：模型可在受最大轮次限制的服务端循环中自主选择工具。只读工具可自动执行；任何有副作用的工具都必须位于请求显式允许的工具范围内，确认必须与预批准的完整 JSON 参数精确匹配并且只能消费一次。调用 ID、参数指纹和确认状态会使用独立短超时尝试写入本地事件审计。

Agent 自主请求支持 `parallel_tool_calls` 控制同轮多调用；Tomur 仍按顺序执行并逐次审计，以保持副作用确认边界。当前宿主配置为 Microsoft Agent Framework `1.19.0`，`GET /api/agents/runtime` 会报告实际程序集版本及已接入的审批响应绑定、流式 Agent、workflow composition 和 usage aggregation 能力面。该包升级后的构建、测试和真实模型 smoke 尚未执行。

`plate.recognize` 已作为 controlled 模式下的只读本地工具接入，使用 `tomur-plate` 稳定 C ABI 调用 HyperLPR3 C++/MNN，并返回车牌文本、业务色码、`VehicleId`、识别置信度和候选框。HyperLPR3 模型权重不进入程序或 native bundle，必须独立放置于 `<data>/models/plate/hyperlpr3/r2_mobile`。M10 `70/70`、M13 `25/25` 自动化测试已通过，HyperLPR3 3.0、MNN 2.2.0、OpenCV 4.12.0 和 bridge 的 Linux ARM64 CPU 原生构建也已完成 ELF、C ABI 与依赖闭包校验；真实图片识别和目标机 smoke 仍待执行。

车牌能力之外的既有工具调用基础代码已通过 M10 专项 `49/49` 自动化测试和 win-x64 Native AOT 发布；工具调用 streaming 当前在完整推理和协议解析后发送可聚合帧，不是逐 token 参数增量。真实模型 smoke、完整 Agent 工具循环、请求取消后的副作用审计和并发事件日志仍未验证。

## 🔌 API 示例

健康检查：

```powershell
curl.exe http://127.0.0.1:5137/health
```

列出本地可见模型：

```powershell
curl.exe http://127.0.0.1:5137/v1/models
```

调用 OpenAI 风格聊天接口：

```powershell
curl.exe http://127.0.0.1:5137/v1/chat/completions `
  -H "Content-Type: application/json" `
  -d '{
    "model": "qwen35-9b-q4km",
    "messages": [
      { "role": "user", "content": "用一句话介绍 Tomur。" }
    ],
    "stream": false
  }'
```

声明一个由客户端执行的 OpenAI 工具：

```powershell
curl.exe http://127.0.0.1:5137/v1/chat/completions `
  -H "Content-Type: application/json" `
  -d '{
    "model": "qwen35-9b-q4km",
    "messages": [
      { "role": "user", "content": "检查当前 Tomur runtime 状态。" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_runtime_status",
          "description": "读取客户端可访问的 Tomur runtime 状态",
          "parameters": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        }
      }
    ],
    "tool_choice": "auto",
    "stream": false
  }'
```

如果模型返回 `choices[0].message.tool_calls`，客户端执行对应函数，再把原 assistant 消息和 `{ "role": "tool", "tool_call_id": "<call-id>", "content": "<tool-result>" }` 追加到 `messages` 后重新请求。Ollama 兼容入口使用对应的 `message.tool_calls` 与 `role=tool` 消息完成同一循环。

调用 Ollama 风格聊天接口：

```powershell
curl.exe http://127.0.0.1:5137/api/chat `
  -H "Content-Type: application/json" `
  -d '{
    "model": "qwen35-9b-q4km",
    "messages": [
      { "role": "user", "content": "列出当前 runtime 状态。" }
    ],
    "stream": false
}'
```

调用 Claude Code / Anthropic Messages 风格聊天接口：

```powershell
curl.exe "http://127.0.0.1:5137/v1/models?limit=1000"

curl.exe http://127.0.0.1:5137/v1/messages `
  -H "Content-Type: application/json" `
  -H "anthropic-version: 2023-06-01" `
  -d '{
    "model": "claude-tomur-qwen35-9b-q4km-<hash>",
    "max_tokens": 512,
    "messages": [
      { "role": "user", "content": "用一句话介绍 Tomur。" }
    ],
    "stream": false
  }'
```

`GET /v1/models?limit=1000` 会为本地文本模型返回 `claude-tomur-*` 发现别名；实际可用别名以本地模型列表为准。

实际可用模型名来自本地安装清单与模型目录。可使用以下命令查看：

```powershell
tomur list
tomur ps
tomur list --catalog
```

## 🏗️ 架构概览

Tomur 保持单进程产品边界。仓库按主程序、托管模型 provider、native runtime、Web 工作台和验证项目组织：

```text
Tomur/
  Tomur.slnx
  app/
    Tomur.csproj
    Program.cs
    Agents/
    Api/
      Anthropic/
      Ollama/
      OpenAI/
    Assets/
    Cli/
    Config/
    Conversations/
    Diagnostics/
    Hardware/
    Inference/
    Models/
    Multimodal/
    Native/
    PlateRecognition/
    Providers/
    Runtime/
    Serialization/
    Services/
    Storage/
    wwwroot/
  providers/
    Abstractions/
      Tomur.Providers.Abstractions.csproj
    Glm/
      Tomur.Providers.Glm.csproj
    Olmoe/
      Tomur.Providers.Olmoe.csproj
  tests/
    Tomur.Providers.M1.Tests/ ... Tomur.Providers.M13.Tests/
    Tomur.Providers.Olmoe.Tests/
  native/
    bundle.manifest.json
    llama.cpp/
    llama.native/
    whisper.cpp/
    whisper.native/
    paddleocr/
    ocr.native/
    stable-diffusion.cpp/
    stable-diffusion.native/
    plate.native/
    tts.native/
  web/
    package.json
    src/
      app/
      components/
  docs/
  README.md
  README.en.md
  ROADMAP.md
  CHANGELOG.md
```

`app/Tomur.csproj` 是唯一产品宿主，承载 CLI、ASP.NET Core 本地 HTTP API、系统服务与托盘启动、模型和会话管理、runtime 诊断以及 Web 静态资源托管。`Program.cs` 只负责进程入口、顶层命令分发和全局帮助；`app/Cli/ServeCommand.cs` 组装同一套本地服务 host，`app/Api/` 提供 Tomur API 与 OpenAI、Ollama、Anthropic Messages 兼容入口，`app/Realtime/` 承载本地 WebSocket 协议、认证、配额与 session 生命周期。

`providers/Abstractions` 保存主程序与托管 provider 共用的模型描述、manifest、推理和 session 契约。`providers/Glm` 与 `providers/Olmoe` 实现纯 C# 模型加载和生成；OLMoE 当前同时复用 GLM 项目的托管 tensor、kernel 与存储基础。主程序直接引用并注册这两个 provider，再根据本地模型格式、架构和 manifest 显式选择；未匹配的 GGUF 文本与 embedding 模型继续使用 llama.cpp 路径。provider 类库不提供独立进程或另一套 HTTP API。

`native/` 保存上游源码、Tomur CMake 适配工程和 `bundle.manifest.json` 发布清单。`app/Native/` 负责 bundle 准备、动态库解析和加载，`app/Inference/` 承载 llama.cpp 文本 session，`app/Multimodal/` 连接 Whisper、OCR、stable-diffusion.cpp 与 GGUF TTS，`app/PlateRecognition/` 通过独立的 HyperLPR3/MNN C ABI 提供车牌识别。纯托管 provider 与这些 native runtime 并行存在，不替换现有 native 能力。

`web/` 使用 React、TypeScript、Vite 与 Ant Design X；依赖由 `package-lock.json` 固定，`Tomur.csproj` 在编译前按源文件变化增量生成 `app/wwwroot`，刷新嵌入资源后由 Tomur 本地 HTTP 服务托管。`tests/` 中的 M1-M13 项目覆盖 GLM provider 的分阶段契约与回归，OLMoE 与 Realtime 使用独立测试项目；它们只属于验证面，不形成产品服务。

## 📁 本地状态

Tomur 使用稳定的数据目录保存配置、模型、runtime 缓存、SQLite 数据库、日志和生成产物。

| 平台 | 默认数据目录 |
| --- | --- |
| Windows | `%LOCALAPPDATA%\Tomur` |
| Linux | `~/.local/share/tomur` |
| macOS | `~/Library/Application Support/Tomur` |

数据目录内的关键路径：

| 路径 | 用途 |
| --- | --- |
| `<data>/config/tomur.json` | 本地配置文件 |
| `<data>/tomur.db` | SQLite 数据库 |
| `<data>/runtime` | 版本化 native runtime 缓存 |
| `<data>/models` | 本地模型目录与安装清单 |
| `<data>/logs` | 日志目录 |

可通过 `--data-dir <path>` 或 `TOMUR_DATA_DIR` 覆盖数据目录。配置文件损坏时，诊断流程会把损坏文件移动为 `.damaged-<timestamp>`，再写入默认配置。

## 📦 运行时资产

Tomur 的发布产物应携带必要的 C++ native dynamic libraries，并在首次运行或版本变化时准备到 Tomur 管理的 runtime 目录。模型权重不会被打包进程序二进制，而是由 `tomur pull` 下载到本地模型目录，并登记到 `<data>/models/models.manifest.json`。

纯托管 provider 集合由 `Tomur.csproj` 的项目引用在构建时确定，GLM 与 OLMoE provider 在进程启动时通过 `ModelProviderRegistry` 静态注册，不从外部 `providers/` 目录动态发现程序集。模型 manifest 仍负责声明 provider、架构和格式；构建未包含对应 provider 或模型资产不完整时，Catalog、API、doctor 与 Runtime UI 返回明确诊断。Native AOT 与非 AOT 发布使用各自构建中已纳入的 provider 集合，该边界不影响现有 native provider 的发布和使用。

`tomur native prepare` 用于释放或修复 native runtime bundle；`tomur doctor` 用于检查 runtime、模型、SQLite、端口、代理与硬件状态。缺失或损坏的 native library 会通过 CLI、API 和 UI 返回明确诊断。

Windows x64 native 构建入口：

```powershell
tomur native build --rid win-x64 --backend all
tomur native build --rid win-x64 --backend vulkan
tomur native build --rid win-x64 --backend sycl
tomur native build --rid win-x64 --backend openvino
tomur native build --rid win-x64 --backend intel
```

`--backend cpu` 与 `--backend cuda13` 可只构建单一变体；`--backend intel` 会构建 llama.cpp 的 `sycl`、`openvino` 与 `vulkan` dynamic backend 入口。缺失 Intel backend 或设备不可枚举时，Tomur 会保留 CPU fallback 并在 `tomur doctor`、`/api/runtime/status` 和 Web Runtime 面板中显示原因。

## 🙏 致谢

Tomur 的纯 C# GLM / MoE provider 在设计灵感与工程思路上受到 [JustVugg/colibri](https://github.com/JustVugg/colibri) 的启发，特别是其使用纯 C 探索 MoE 模型运行、从磁盘流式读取 routed experts，以及管理常驻权重与多级缓存的实践。感谢 JustVugg 公开并分享这些工作。Tomur 以 C# 独立实现相关能力，Colibri 不作为 Tomur 的运行时依赖。

R21 的视觉能力矩阵、统一同步/异步推理接口和 ONNX 模型组织思路受到 [javpower/rust-onnx-infer](https://gitee.com/javpower/rust-onnx-infer) 的公开工作启发。感谢 javpower 分享这套 Rust/ONNX Runtime 视觉推理实现。Tomur 将在 C# 单进程边界内独立实现和验证相关能力，不把该项目作为运行时依赖；具体代码与模型资产仍须逐项遵守上游及第三方许可。

## 📄 开源许可

Tomur 由 IoTSharp contributors 以 [Apache License 2.0](./LICENSE) 发布。该许可覆盖 Tomur 自有源代码；第三方依赖、native runtime、可选加速库和模型资产继续适用各自的上游许可，不因 Tomur 的主许可证而重新授权。版权声明与分发边界见 [NOTICE](./NOTICE) 和 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

## 🗺️ 路线图

长期阶段计划、完成口径和后续工作维护在 [ROADMAP.md](./ROADMAP.md)；已完成历史维护在 [CHANGELOG.md](./CHANGELOG.md)。README 只保留项目首页所需的定位、使用路径和当前边界。

R22 规划通过同进程 C# provider 接入 [Sezika](https://github.com/IoTSharp/Sezika) 多语言非自回归决策引擎，为本地状态提供类型化选择、评分和真假概率。Sezika 已有纯 C# CPU typed engine，以及 CUDA Driver 固定 PTX/GEMM 决策头和 win-x64 Native AOT smoke；真实发布模型、完整 GPU encoder 与 Tomur provider/API 仍待接入和验证。见 [R22 设计](./docs/r22-decision-engine.md)。