# qniuma

**Repository Path**: jinxinyang/qniuma

## Basic Information

- **Project Name**: qniuma
- **Description**: 分布式llm算力集市
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QNIUMA - 分布式协作 LLM 推理算力共享平台

> **每个设备都运行模型切片，多设备协作完成大模型推理**

## 项目简介

QNIUMA 是一个创新的分布式协作推理平台。与传统分布式计算不同，我们不是让高端设备独立运行大模型，而是**让每个设备都运行模型的切片**，多设备协作完成同一个推理任务。

### 核心创新

```
传统方式:                    QNIUMA 方式:
┌──────────────┐            ┌──────────────┐
│ 高端 PC      │            │ 设备 A       │
│ 独立运行 7B  │            │ 层 0-3       │
│              │            ├──────────────┤
│              │            │ 设备 B       │
│              │            │ 层 4-7       │
└──────────────┘            ├──────────────┤
                            │ 设备 C       │
低端设备无法参与             │ 层 8-11      │
                            ├──────────────┤
                            │ ...          │
                            └──────────────┘

所有设备都参与！
```

### 核心特性

- **真正的协作推理**: 每个设备负责几层 Transformer，一起完成 7B 模型推理
- **极低门槛**: 512MB 内存即可参与（跑 2-3 层）
- **高可用容错**: 设备掉线自动重组，备用节点秒级替补
- **公平收益**: 根据贡献的层数计算积分，每个参与者都有回报

```
QNIUMA/
├── backend/                 # Go 后端服务
│   ├── cmd/
│   │   ├── api/            # REST API + gRPC 服务器
│   │   ├── scheduler/      # 任务调度器
│   │   └── worker/         # 后台工作进程
│   ├── internal/
│   │   ├── auth/           # JWT 认证
│   │   ├── config/         # 配置管理
│   │   ├── database/       # 数据库连接
│   │   ├── models/         # 数据模型
│   │   ├── handler/        # HTTP 处理器
│   │   ├── middleware/     # 中间件
│   │   ├── node/           # 节点管理
│   │   ├── scheduler/      # 调度逻辑
│   │   └── task/           # 任务处理
│   └── go.mod
│
├── client/                  # Tauri 桌面客户端
│   ├── src-tauri/          # Rust 核心
│   │   ├── src/
│   │   │   ├── capability/ # 设备能力检测
│   │   │   ├── distributed/ # 分布式推理核心
│   │   │   ├── config/     # 配置管理
│   │   │   ├── network/    # 网络通信
│   │   │   └── inference/  # 推理引擎
│   │   ├── Cargo.toml
│   │   └── tauri.conf.json
│   ├── src/                # React 前端
│   │   ├── App.tsx
│   │   └── styles.css
│   ├── package.json
│   └── vite.config.ts
│
├── proto/                   # Protocol Buffers 定义
│   ├── distributed.proto   # 分布式推理服务
│   ├── inference.proto     # 推理服务
│   ├── node.proto          # 节点服务
│   └── task.proto          # 任务服务
│
├── scripts/                 # 工具脚本
│   └── init.sql            # 数据库初始化
│
├── docs/                    # 文档
│   ├── 低配置设备支持方案.md
│   └── 详细开发计划.md
│
├── docker-compose.yml       # 本地开发环境
├── CLAUDE.md               # AI 助手指南
└── README.md               # 本文件
```

## 技术栈

### 后端 (Go)
- **框架**: Gin (REST), gRPC
- **数据库**: PostgreSQL (主), MongoDB (日志), InfluxDB (指标)
- **缓存**: Redis
- **消息队列**: NATS JetStream
- **存储**: MinIO (模型文件)

### 客户端 (Tauri)
- **核心**: Rust + llama.cpp
- **UI**: React + Vite + Tailwind CSS
- **通信**: gRPC + WebSocket

## 📚 文档导航

| 文档 | 说明 |
|------|------|
| **[USER_GUIDE.md](USER_GUIDE.md)** | 用户使用指南 - 普通用户快速上手 |
| **[BUILD_GUIDE.md](BUILD_GUIDE.md)** | 构建指南 - 开发者从源码构建 |
| **[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)** | 部署指南 - 生产环境部署文档 |
| **[QUICKSTART.md](QUICKSTART.md)** | 快速开始 - 本地开发环境 |

---

## 快速开始

### 🚀 对于普通用户 (直接使用)

#### Windows 用户
1. 下载预编译的 `qniuma-client.exe`
2. 双击运行即可
3. 详细使用说明请参考 [USER_GUIDE.md](USER_GUIDE.md)

#### 功能特性
- ✅ 自动检测设备硬件 (CPU/GPU/内存/磁盘)
- ✅ 一键下载 AI 模型
- ✅ 三个标签页: 控制面板 / 系统配置 / 推理测试
- ✅ 实时显示贡献状态和积分

---

### 👨‍💻 对于开发者 (从源码构建)

#### 环境要求

- Rust stable
- Node.js 18+
- (可选) Go 1.21+ (用于后端开发)
- (可选) Docker & Docker Compose (用于本地开发环境)

#### 1. 启动基础设施

```bash
docker-compose up -d
```

这将启动：
- PostgreSQL (端口 5432)
- Redis (端口 6379)
- NATS (端口 4222)
- MinIO (端口 9000/9001)
- Prometheus (端口 9090)
- Grafana (端口 3000)

### 2. 初始化数据库

```bash
psql -h localhost -U qniuma -d qniuma -f scripts/init.sql
```

### 3. 启动后端服务

```bash
cd backend
go run cmd/api/main.go
```

API 服务将在 http://localhost:8080 启动

### 4. 启动客户端

```bash
cd client
npm install
npm run tauri dev
```

## 设备支持矩阵（分布式协作）

**所有设备都参与同一个 7B 模型的推理！**

| 设备等级 | 内存 | 负责层数 | 内存占用 | 收益 |
|----------|------|----------|----------|------|
| Ultra | 16GB+ | 16-28 层 | ~2GB | 35 积分/小时 |
| High | 8-16GB | 8-16 层 | ~1GB | 22 积分/小时 |
| Medium | 4-8GB | 4-8 层 | ~500MB | 14 积分/小时 |
| Low | 2-4GB | 2-4 层 | ~300MB | 8 积分/小时 |
| Minimal | 512MB+ | 2 层 | ~250MB | 4 积分/小时 |

详细说明请参考 [docs/分布式协作推理架构.md](docs/分布式协作推理架构.md)

## 开发计划

12 周 MVP 路线图，详见 [docs/详细开发计划.md](docs/详细开发计划.md)

| 周次 | 里程碑 |
|------|--------|
| W1 | 项目初始化与环境搭建 |
| W2 | 数据库设计与认证系统 |
| W3 | 设备检测系统 |
| W4 | 前端 UI 开发 |
| W5 | llama.cpp 集成 |
| W6 | 任务调度系统 |
| W7 | gRPC 通信 |
| W8 | 积分系统 |
| W9 | 模型分发系统 |
| W10 | 监控与日志 |
| W11 | 测试与优化 |
| W12 | MVP 发布 |

## API 端点

### 认证
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/refresh` - 刷新令牌

### 节点
- `GET /api/v1/nodes` - 列出用户节点
- `POST /api/v1/nodes` - 注册新节点
- `POST /api/v1/nodes/:id/heartbeat` - 节点心跳

### 任务
- `POST /api/v1/tasks` - 创建推理任务
- `GET /api/v1/tasks/:id` - 获取任务详情
- `GET /api/v1/tasks/:id/result` - 获取任务结果 (SSE)

### 积分
- `GET /api/v1/credits/balance` - 查询余额
- `GET /api/v1/credits/transactions` - 交易历史

## 配置说明

客户端配置位于 `~/.config/qniuma/config.json`：

```json
{
  "server": {
    "api_url": "https://api.qniuma.com",
    "grpc_url": "grpc.qniuma.com:50051"
  },
  "model": {
    "name": "Qwen2.5-7B-Instruct (协作推理)",
    "quantization": "Q4_K_M",
    "max_context_length": 32768
  },
  "contribution": {
    "mode": "DistributedInference",
    "max_cpu_usage": 80,
    "only_when_idle": true
  }
}
```

## 贡献指南

我们欢迎所有形式的贡献！

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

MIT License - 详见 LICENSE 文件

## 联系方式

- 项目主页: https://github.com/qniuma/qniuma
- 文档: https://docs.qniuma.com
- 邮箱: contact@qniuma.com

---

<promise>加细化的颗粒度的计划，每一个步骤都能很好的落地并支撑最终的结果</promise>