# ai开源

**Repository Path**: stoneqweadsa/open-source-ai

## Basic Information

- **Project Name**: ai开源
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 荧惑 · Yinghuo —— 开源 AI 大模型

**荧荧如火，洞察万物。**

「荧惑」是火星在中国古代的名字。作为一款开源 AI 大模型，荧惑以开源基座
（Qwen / Llama / GLM / DeepSeek …）为起点，通过 LoRA 微调注入专属人格与领域知识，
对外提供对话、检索增强（RAG）、Agent 工具调用、通用 NLP 与多模态能力。

> 技术底座 **Open Source AI**：统一开源 AI 能力平台，Python 负责模型编排与能力封装，
> C++ 负责高性能算子加速。完整架构见 **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。

---

## 关于荧惑

| 维度 | 说明 |
|---|---|
| 名字 | 「荧惑」为火星古称，取「荧荧如火、明灭有致」之意，寓意理性而敏锐的思考 |
| 定位 | 开源、可自托管、可私有化部署的通用 AI 大模型 |
| 基座 | 开源权重（Qwen / Llama / GLM / DeepSeek …）择优接入 |
| 训练路线 | LoRA 低秩微调：在基座之上注入专属人设、语气与领域知识，不破坏基座通用能力 |
| 能力 | 对话 / 流式输出 / RAG 检索增强 / ReAct Agent / 通用 NLP / 多模态 |
| 交付形态 | OpenAI 兼容 API、Web UI、CLI、Python SDK 四合一 |
| 部署 | 零依赖即可启动；支持 CPU 量化推理与 GPU 加速 |

---

## 桌面版（下载即用）

Windows 用户不需要装 Python，两种方式：

| 方式 | 文件 | 说明 |
|---|---|---|
| **安装包**（推荐） | `release/荧惑安装包-win64.exe` | 双击 → 下一步 → 自动建快捷方式；设置里可正常卸载 |
| 绿色版 | `release/Yinghuo-win64.zip` | 解压即用，不写注册表，删目录即卸载 |

装好后第一次打开会自动停在「模型」页，点第一个「下载」：从 ModelScope 拉取
`Qwen2.5 0.5B`（约 470 MB），完成后直接对话。**不需要 Ollama、不需要 Python、不需要编译、
也不需要联网装引擎**——推理引擎（荧惑引擎，含 llama.cpp 内核，约 60 MB）已经随安装包分发。
不过模型权重较大，仍按需下载。

### 荧惑引擎（自有推理引擎）

`src/opensourceai/inference/` 是这层引擎的实现，安装包直接携带，装完即可推理：

| 模块 | 作用 |
|---|---|
| `gguf.py` | 纯标准库解析 GGUF 头：架构、层数、头数、上下文、量化、参数量 |
| `tuning.py` | 按「模型规格 × 本机内存」自动算线程 / 上下文 / 批大小 / 内存锁定 |
| `bundled.py` | 定位随包分发的运行时，找不到才回退到在线下载 |

运行时参数会自动适配引擎版本（例如新版用 `-fa on` + `-lm mmap+mlock`，老版用 `--mlock`），
换机器、换模型都不用手工调。

> **老实说**：0.5B / 1.5B 这类小模型只能做到「离线能说话」，知识量与推理远不如豆包、DeepSeek。
> 想要接近它们的体验，二选一：下载 7B 以上的模型，或直接接云端大模型（下面这条路更省事）。

## 云端模型（推荐）

界面「模型 → 云端模型」填一个 API Key 即可，**热切换、无需重启**：

| 服务商 | 地址 | 典型模型 |
|---|---|---|
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` / `deepseek-reasoner` |
| 豆包 · 火山方舟 | `https://ark.cn-beijing.volces.com/api/v3` | 接入点 ID（`ep-` 开头） |
| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
| Moonshot | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | `glm-4-plus` |
| 任意自建网关 | 自己填 | 自己填 |

```bash
# 也可以用环境变量
OSAI_BACKEND=openai OSAI_API_BASE=https://api.deepseek.com/v1 \
OSAI_API_KEY=sk-xxx OSAI_API_MODEL=deepseek-chat python launcher.py
```

密钥只写入本机 `~/.open-source-ai/config.json`，接口回显一律打码（`sk-****cdef`），
不会进入日志与仓库。点「断开」即可回落到本地模型。
有 pywebview 时是独立窗口，没有则自动用系统浏览器打开。

命令行同样一条命令搞定：

```bash
osai model pull qwen2.5-0.5b-q4   # 自动装引擎 + 下载模型 + 切换
osai chat
```

不装包也能看成品——仓库根目录带一个零依赖启动器：

```bash
python launcher.py            # 一键启动并打开界面（自动复用已运行实例）
python launcher.py --check    # 环境自检：内存、引擎、已装模型、推荐模型
python launcher.py --port 9000 --no-browser   # 指定端口、只起服务
```

```bash
osai app                       # 从源码启动桌面版
python scripts/fetch_engine.py # 准备随包分发的推理引擎 → vendor/engine/
python scripts/build_app.py    # 打包桌面程序 → dist/Yinghuo/ + release/Yinghuo-win64.zip
python scripts/build_installer.py  # 打包安装包 → release/荧惑安装包-win64.exe
```

安装位置默认 `%LOCALAPPDATA%\Programs\Yinghuo`，免管理员权限；
静默安装 `荧惑安装包-win64.exe /S /D=D:\Apps\Yinghuo`。
完整的安装、卸载、静默参数与打包原理见 **[docs/DESKTOP.md](docs/DESKTOP.md)**。

---

## 定位说明

本项目是**开源模型的编排、微调与产品化平台**，承载「荧惑」大模型从微调到落地的完整链路。

- ✅ 加载并编排任意开源权重（Qwen / Llama / GLM / DeepSeek / Baichuan …）
- ✅ 基于开源基座做 LoRA 微调，注入「荧惑」专属人设与领域知识
- ✅ 提供对话、RAG、Agent 工具调用、通用 NLP、多模态等通用 AI 能力
- ✅ 核心链路**零第三方依赖**即可运行，重量级依赖按需加载
- ❌ 不从零预训练大模型（避免海量数据与算力投入，聚焦落地与个性化）
- ❌ 不提供任意代码执行等高危工具

---

## 核心特性

| 特性 | 说明 |
|---|---|
| 四类后端自动降级 | transformers → llama.cpp → Ollama → 纯规则回退，任何环境都能启动 |
| OpenAI 兼容 | `/v1/chat/completions` 等接口与 OpenAI 一致，现有工具链零改造接入 |
| 完整 RAG | 分块 → 嵌入 → 向量检索 → 带引用的问答 |
| ReAct Agent | 内置安全工具集（计算器 / 时间 / 文本统计 / JSON 抽取）+ 知识库检索工具 |
| 通用 NLP 任务 | 翻译、摘要、分类、情感、关键词、代码生成、改写、结构化抽取 |
| 多模态 | 图像理解、语音识别、语音合成、文生图（依赖就绪即用） |
| C++ 加速层 | 余弦/top-k 检索、UTF-8 安全分块；未编译时自动降级纯 Python |
| 零依赖可用 | 核心功能不装任何第三方包也能跑通全流程 |

---

## 当前进度

| 阶段 | 内容 | 状态 |
|---|---|---|
| Phase 1 | 基础架构：配置、类型、异常、日志、C++ 算子层、ctypes 桥接、核心层 | ✅ 已完成 |
| Phase 2 | 模型接入：四类后端 + auto 工厂 | ✅ 已完成 |
| Phase 3 | 能力层：对话、RAG、Agent、NLP、多模态、Engine 门面 | ✅ 已完成 |
| Phase 4 | 接入层：FastAPI 服务、Web UI、CLI | ✅ 已完成 |
| Phase 5 | 质量保障：测试套件、冒烟脚本、构建脚本、CI | ✅ 已完成 |
| Phase 6 | 增强：ANN 索引、缓存落盘、SIMD 优化、多模态 UI | 🔜 规划中 |
| 荧惑微调 | LoRA 链路：人设 → 数据 → 训练 → 导出 → 评估 | ✅ 已完成 |
| 桌面分发 | 品牌图标、模型中心、零依赖本地服务、启动器、安装包 | ✅ 已完成 |
| 对话界面 | 会话管理、Markdown/表格/代码块、停止与重生成、主题切换、设置抽屉 | ✅ 已完成 |

> 详细进度与剩余待办见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 第 14、16 节。
> 每次接手前请先阅读根目录 [TODO.md](TODO.md)，按清单推进。

---

## 环境要求

- Python 3.9+
- （可选）C++17 编译器 + CMake 3.16+，用于构建加速层
- （可选）本地模型：GGUF 文件 / Ollama 服务 / HuggingFace 权重

---

## 快速开始

### 1. 安装

```bash
# 仅核心（零第三方依赖）
pip install -e .

# 完整能力（体积较大，按需）
pip install -r requirements-full.txt
```

### 2. 配置模型（任选其一）

```bash
# 方式 A：Ollama（推荐，最简单）
ollama serve
ollama pull qwen2.5:7b
export OSAI_BACKEND=ollama
export OSAI_MODEL=qwen2.5:7b

# 方式 B：llama.cpp GGUF
export OSAI_BACKEND=llamacpp
export OSAI_MODEL=/path/to/model.gguf

# 方式 C：transformers（GPU）
export OSAI_BACKEND=transformers
export OSAI_MODEL=Qwen/Qwen2.5-7B-Instruct

# 不配置任何模型也能启动，会进入离线回退模式
```

### 3. 构建 C++ 加速层（可选）

```bash
cmake -S src/cpp -B build
cmake --build build --config Release
```

未构建时自动使用纯 Python 实现，功能完全等价。

### 4. 使用（Python SDK）

```python
from opensourceai import Engine

engine = Engine.from_env()

print(engine.chat("用一句话介绍你自己"))

engine.ingest("docs/")                       # 摄入知识库
print(engine.rag_query("架构分为哪几层？"))   # 带引用的问答

result = engine.agent("计算 (3+5)*7 再告诉我现在几点")
print(result.answer, result.tools_used)
```

### 5. 启动 Web 界面 / HTTP 服务

```bash
osai serve --host 0.0.0.0 --port 8000
```

打开 `http://127.0.0.1:8000/` 即可使用内置对话界面（对话 / 知识库 / Agent 三模式），
接口文档见 `http://127.0.0.1:8000/docs`，完全兼容 OpenAI 协议。

### 6. 运行测试

```bash
python scripts/smoke.py   # 零依赖端到端冒烟（无需模型）
pytest -q                 # 全量单测（需 pip install -e ".[dev,server]"）
```

### 7. 微调自己的「荧惑」

```bash
# 1) 校验并构建 SFT 数据集（零依赖）
python scripts/build_dataset_yinghuo.py --check

# 2) 先看训练计划，不装 torch 也能跑
python scripts/finetune_yinghuo.py --dry-run

# 3) 真实训练（需 pip install torch transformers peft accelerate）
python scripts/finetune_yinghuo.py --base Qwen/Qwen2.5-0.5B-Instruct --epochs 3

# 4) 挂载 adapter 推理
export OSAI_BACKEND=transformers OSAI_ADAPTER_PATH=output/yinghuo-lora
osai chat

# 5) 规则化评估与前后对比
python scripts/eval_yinghuo.py --self-test
python scripts/eval_yinghuo.py --out output/eval-lora.json
```

完整参数、显存对照与排错表见 **[docs/FINETUNE.md](docs/FINETUNE.md)**。

---

## 目录结构

```
open-source-ai/
├── assets/brand/             # 图标源资产（png / ico / svg）
├── docs/
│   ├── ARCHITECTURE.md       # 架构与实现方案
│   ├── FINETUNE.md           # 荧惑微调与落地手册
│   └── DESKTOP.md            # 桌面版下载与打包
├── data/yinghuo/             # SFT 种子数据、构建产物、评估用例
├── packaging/                # PyInstaller 入口脚本
├── src/cpp/                  # C++ 高性能算子层（可选）
├── src/opensourceai/         # Python 包
│   ├── core/                 # 零依赖核心层
│   ├── backends/             # 模型后端抽象与实现
│   ├── inference/            # 荧惑推理引擎：GGUF 解析 / 自动调参 / 内置运行时
│   ├── capabilities/         # 对话 / RAG / Agent / NLP / 多模态
│   ├── serving/              # FastAPI 服务 + 零依赖桌面服务
│   ├── desktop/              # 桌面启动器
│   ├── ui/                   # 单文件 Web 界面与图标
│   ├── persona.py            # 荧惑人设内核（训练与推理同源）
│   ├── model_hub.py          # 模型中心（探测 / 下载 / 切换）
│   └── engine.py             # 统一门面
├── scripts/                  # 图标 / 数据 / 微调 / 评估 / 打包 / 冒烟
├── launcher.py               # 源码一键启动器（双击即可预览成品）
├── requirements.txt
└── pyproject.toml
```

---

## 安全提示

- 所有密钥、访问令牌**只能通过环境变量传入**，切勿写入代码或配置文件，更不要提交到仓库。
- 任何曾出现在聊天记录、日志或提交历史中的令牌都应**立即撤销并重新生成**。
- 本项目不提供任意代码执行、任意 URL 抓取等高危工具；`calculator` 使用 AST 白名单求值。

---

## 许可证

[MIT](LICENSE)