# easy_rwkv

**Repository Path**: aierwiki/easy_rwkv

## Basic Information

- **Project Name**: easy_rwkv
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-09
- **Last Updated**: 2025-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy RWKV

一个简单易用的 RWKV 语言模型封装库，让您轻松使用 RWKV 模型进行对话和文本生成。

## ✨ 主要特性

- 🚀 **简单易用**: 一行代码加载 RWKV 模型
- 🎛️ **灵活配置**: YAML 配置文件支持  
- 💬 **交互式命令行**: 美观的终端聊天界面
- 📦 **PyPI 发布**: 可直接 pip 安装
- 🤗 **自动下载**: 支持 Hugging Face 模型自动下载
- 🌐 **镜像支持**: 支持国内镜像站点加速下载
- 🔧 **跨平台**: 支持 Windows、macOS、Linux

## 🚀 快速开始

### 安装

```bash
pip install easy-rwkv
```

或从源码安装：

```bash
git clone https://github.com/your-username/easy-rwkv.git
cd easy-rwkv
pip install -e .
```

### 基础使用

```python
from easy_rwkv import EasyRWKV, Config

# 创建配置
config = Config()
config.model_path = "BlinkDL/rwkv-7-world/RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth"
config.strategy = "cpu fp32"  # 或 "cuda fp16" (如果有GPU)

# 创建模型实例
rwkv = EasyRWKV(config)

# 开始对话
response = rwkv.chat("你好，请介绍一下你自己。")
print(response)
```

### 命令行使用

```bash
# 启动交互式聊天
easy-rwkv chat --model "BlinkDL/rwkv-7-world/RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth"

# 使用配置文件
easy-rwkv chat --config config.yaml

# 交互式配置
easy-rwkv chat --interactive-setup
```

## 📥 模型下载

### 自动下载

Easy RWKV 支持自动下载 Hugging Face 上的模型：

```python
# 直接使用 HF 模型路径，系统会自动下载
config.model_path = "BlinkDL/rwkv-7-world/RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth"
```

### 加速下载（中国用户）

```bash
# 设置镜像站点环境变量
export HF_ENDPOINT=https://hf-mirror.com

# 或在代码中设置
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
```

### 推荐模型

| 模型名称 | 大小 | 描述 | 适用场景 |
|---------|------|------|----------|
| `RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth` | 364MB | 小型测试模型 | 快速体验、开发测试 |
| `RWKV-x070-World-0.4B-v2.9-20250107-ctx4096.pth` | 800MB+ | 中型模型 | 日常对话、轻量应用 |
| `RWKV-x070-World-1.5B-v3-20250127-ctx4096.pth` | 3GB+ | 大型模型 | 专业应用、高质量生成 |

更多模型请访问 [BlinkDL/rwkv-7-world](https://huggingface.co/BlinkDL/rwkv-7-world)。

## ⚙️ 配置文件

创建 `config.yaml` 文件：

```yaml
# 模型配置
model_path: "BlinkDL/rwkv-7-world/RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth"
strategy: "cpu fp32"           # cpu fp32, cuda fp16, etc.
state_path: null               # 可选的状态文件路径

# 生成参数
temperature: 1.0               # 生成温度 (0.1-2.0)
top_p: 0.3                    # Top-p 采样 (0.0-1.0)
max_tokens: 256               # 最大生成长度

# RWKV 特定设置
rwkv_v7_on: true              # 启用 RWKV-7 支持
rwkv_jit_on: true             # 启用 JIT 编译
rwkv_cuda_on: false           # macOS 用户设为 false
```

## 🎮 命令行界面

启动交互式聊天后，您可以使用以下命令：

- `/help` - 显示帮助信息
- `/reset` - 重置对话状态  
- `/info` - 显示模型信息
- `/config` - 显示当前配置
- `/exit` 或 `/quit` - 退出程序

## 📚 API 参考

### EasyRWKV 类

```python
from easy_rwkv import EasyRWKV, Config

# 初始化
rwkv = EasyRWKV(config)          # 使用配置对象
rwkv = EasyRWKV.from_file("config.yaml")  # 从文件加载

# 主要方法
rwkv.load_model()               # 加载模型
rwkv.chat(message)              # 单轮对话
rwkv.reset_state()              # 重置对话状态
rwkv.get_model_info()           # 获取模型信息
```

### Config 类

```python
from easy_rwkv import Config

# 创建配置
config = Config()
config.model_path = "model_path"
config.strategy = "cpu fp32"
config.temperature = 1.0
config.top_p = 0.3

# 从文件加载/保存
config = Config.from_file("config.yaml")
config.save_to_file("config.yaml")
```

## 🛠️ 开发指南

### 环境要求

- Python 3.8+
- PyTorch 1.13.0+
- 足够的内存（取决于模型大小）

### 安装开发依赖

```bash
git clone https://github.com/your-username/easy-rwkv.git
cd easy-rwkv
pip install -e ".[dev]"
```

### 运行测试

```bash
python quick_test.py          # 快速验证
python test_installation.py  # 安装测试
python demo.py               # 完整示例
```

### 查看可用模型

```bash
python list_all_models.py
```

## 🚨 故障排除

### 常见问题

**Q: 模型下载失败**
```bash
# 解决方案：使用镜像站点
export HF_ENDPOINT=https://hf-mirror.com
```

**Q: CUDA 相关错误（macOS）**
```yaml
# config.yaml 中设置
strategy: "cpu fp32"
rwkv_cuda_on: false
```

**Q: 内存不足**
```python
# 使用更小的模型
config.model_path = "BlinkDL/rwkv-7-world/RWKV-x070-World-0.1B-v2.8-20241210-ctx4096.pth"
```

**Q: 颜色显示问题**
- 确保终端支持颜色显示
- 系统会自动检测并适配

### 性能优化

1. **GPU 加速**（如有 NVIDIA GPU）：
   ```yaml
   strategy: "cuda fp16"
   rwkv_cuda_on: true
   ```

2. **内存优化**：
   - 选择合适大小的模型
   - 调整 `max_tokens` 参数

3. **生成质量**：
   - 调整 `temperature` (0.1-2.0)
   - 调整 `top_p` (0.0-1.0)

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

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

## 📄 许可证

本项目采用 Apache 2.0 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [RWKV](https://github.com/BlinkDL/RWKV-LM) - 核心模型架构
- [BlinkDL](https://huggingface.co/BlinkDL) - 预训练模型
- [Hugging Face](https://huggingface.co/) - 模型托管平台

## 📊 项目状态

- ✅ 核心功能完整
- ✅ CLI 界面完善
- ✅ 自动下载支持
- ✅ 跨平台兼容
- ✅ 文档完善

**当前版本**: v0.1.0  
**维护状态**: 活跃开发中

---

如有问题或建议，请提交 [Issue](https://github.com/aierwiki/easy-rwkv/issues) 或联系维护者。