ViperEkura
/
AstrAI
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 优化文档结构并添加 GitHub 模板

This commit is contained in:
ViperEkura 2026-03-31 10:00:49 +08:00
parent 2e009cf59a
commit b1527d9575
5 changed files with 361 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
.github/ISSUE_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,41 @@
---
name: Issue Report
about: Report a bug or suggest a feature
title: '[ISSUE] '
labels: ''
assignees: ''
---
## Type
Please select the type of this issue:
- [ ] Bug Report
- [ ] Feature Request
## Description
A clear and concise description of the issue or suggestion.
## Steps to Reproduce (for bugs)
1.
2.
3.
## Expected Behavior (for bugs)
What you expected to happen.
## Actual Behavior (for bugs)
What actually happened.
## Solution Proposal (for features)
Describe the solution you'd like.
## Alternatives Considered (for features)
Describe any alternative solutions or features you've considered.
## Environment (for bugs)
- Python version:
- AstrAI version (or commit hash):
- OS:
- GPU (if applicable):
## Additional Context
Add any other context, screenshots, or logs here.

26
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,26 @@
## Description
Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
Fixes # (issue number)
## Type of Change
Please delete options that are not relevant.
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Other (please describe):
## How Has This Been Tested?
Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.
## Checklist:
- [ ] My code follows the style guidelines of this project (run `ruff format .` and `ruff check --fix .`)
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules

68
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,68 @@
# Contributing to AstrAI
Thank you for your interest in contributing to AstrAI! This document provides guidelines and steps for contributing.
## How to Contribute
### Reporting Issues
If you encounter a bug or have a feature request, please open an issue on GitHub. Include as much detail as possible:
- A clear description of the problem or request.
- Steps to reproduce (for bugs).
- Your environment (Python version, OS, etc.).
### Submitting Changes
1. **Fork** the repository.
2. **Clone** your fork:
```bash
git clone https://github.com/your-username/AstrAI.git
cd AstrAI
```
3. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes**. Follow the code style guidelines below.
5. **Commit your changes** with a descriptive commit message:
```bash
git commit -m "Add: brief description of the change"
```
6. **Push** to your fork:
```bash
git push origin feature/your-feature-name
```
7. **Open a Pull Request** (PR) against the `main` branch of the upstream repository.
## Code Style
AstrAI uses [Ruff](https://docs.astral.sh/ruff/) for code formatting and linting. Please ensure your code is formatted before submitting.
- Run Ruff to format and lint:
```bash
ruff format .
ruff check --fix .
```
- The project uses **double quotes** for strings and **4‑space indentation** (as configured in `pyproject.toml`).
## Testing
If you add or modify functionality, please include appropriate tests.
- Run the test suite with:
```bash
pytest
```
- Ensure all tests pass before submitting your PR.
## Code Review
All submissions will be reviewed. We may request changes or discuss alternatives. Please be responsive to feedback.
## License
By contributing, you agree that your contributions will be licensed under the same [GPL-3.0 License](LICENSE) that covers the project.
---
If you have any questions, feel free to ask in the [GitHub Discussions](https://github.com/ViperEkura/AstrAI/discussions) or open an issue.
Happy contributing!

166
README.md
View File

@ -5,7 +5,7 @@
<div> <div>
<a href="#english">English</a> • <a href="#english">English</a> •
<a href="#chinese">中文</a> <a href="assets/docs/README-zh-CN.md">中文</a>
</div> </div>
<p> <p>
@ -13,23 +13,37 @@
</p> </p>
</div> </div>
## 📖 Table of Contents | 目录 <div align="center">
<img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="python">
<img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="license">
<img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?color=76bad9" alt="release">
<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.stargazers_count&label=stars&suffix=%20stars&color=76bad9" alt="stars">
<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.forks_count&label=forks&suffix=%20forks&color=76bad9" alt="forks">
</div>
<br>
<div align="center">
<a href="#english">English</a> •
<a href="assets/docs/README-zh-CN.md">中文</a> •
<a href="https://github.com/ViperEkura/AstrAI/issues">Issue Tracker</a> •
<a href="https://github.com/ViperEkura/AstrAI/discussions">Discussions</a> •
<a href="https://huggingface.co/ViperEk/AstrAI">HuggingFace</a>
</div>
<br>
## 📖 Table of Contents
<details open> <details open>
<summary><b>English</b></summary> <summary><b>English</b></summary>
- [Installation](#installation) - [Features](#features)
- [Quick Start](#quick-start) - [Quick Start](#quick-start)
- [Documentation](#documentation) - [Documentation](#documentation)
- [Contributing](#contributing)
</details> - [Community](#community)
- [License](#license)
<details>
<summary><b>中文</b></summary>
- [安装](#安装)
- [快速开始](#快速开始)
- [文档](#文档)
</details> </details>
@ -40,59 +54,16 @@
### Features ### Features
- 🚀 **High Performance**: Optimized for both training and inference - 🚀 **High Performance**: Optimized for both training and inference with efficient parallelization.
- 🔧 **Flexible**: Support for seq/sft/dpo training - 🔧 **Flexible**: Support for seq/sft/dpo training, customizable model architectures.
- 💡 **Easy to Use**: Simple API with comprehensive examples - 💡 **Easy to Use**: Simple API with comprehensive examples and demos.
- 📦 **Lightweight**: Minimal dependencies - 📦 **Lightweight**: Minimal dependencies, easy to deploy.
- 🔬 **Research‑Friendly**: Modular design, easy to experiment with new ideas.
### Installation - 🤗 **HuggingFace Integration**: Compatible with HuggingFace models and datasets.
```bash
git clone https://github.com/ViperEkura/AstrAI.git
cd AstrAI
pip install -e .
```
### Quick Start ### Quick Start
```bash #### Installation
# Train
python tools/train.py \
--train_type=seq \
--data_root_path=/path/to/dataset \
--param_path=/path/to/param_path
# Generate
python tools/generate.py --param_path=/path/to/param_path
```
### Demo
```bash
# run download before using
python demo/download.py
# run demo
python demo/stream_chat.py
python demo/generate_batch.py
python demo/generate_ar.py
```
- [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd)
---
<a id="chinese"></a>
## 中文
### 特性
- 🚀 **高性能**: 训练与推理双向优化
- 🔧 **灵活**: 支持 seq/sft/dpo 多种训练方式
- 💡 **易用**: 简洁的 API 与丰富的示例
- 📦 **轻量**: 依赖少，部署简单
### 安装
```bash ```bash
git clone https://github.com/ViperEkura/AstrAI.git git clone https://github.com/ViperEkura/AstrAI.git
@ -100,52 +71,79 @@ cd AstrAI
pip install -e . pip install -e .
``` ```
### 快速开始 For development dependencies:
```bash
pip install -e ".[dev]"
```
#### Train a Model
```bash ```bash
# 训练
python tools/train.py \ python tools/train.py \
--train_type=seq \ --train_type=seq \
--data_root_path=/path/to/dataset \ --data_root_path=/path/to/dataset \
--param_path=/path/to/param_path --param_path=/path/to/param_path
```
# 生成 #### Generate Text
```bash
python tools/generate.py --param_path=/path/to/param_path python tools/generate.py --param_path=/path/to/param_path
``` ```
### 演示 #### Demo
Check out the demos in the `demo/` folder:
```bash ```bash
# 使用前先下载模型 # Download pre‑processed data (required before running demos)
python demo/download.py python demo/download.py
# 运行示例 # Interactive streaming chat
python demo/stream_chat.py python demo/stream_chat.py
# Batch generation
python demo/generate_batch.py python demo/generate_batch.py
# Auto‑regressive generation
python demo/generate_ar.py python demo/generate_ar.py
``` ```
- [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd) Watch a video walkthrough on [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd).
### Documentation
---
<a id="documentation"></a>
### Document | 文档
| Document | Description | | Document | Description |
|----------|-------------| |----------|-------------|
| *Parameter Guide* <br> [参数说明](./assets/docs/params.md) | *Training & inference parameters* <br> 训练与推理参数配置 | | [Parameter Guide](./assets/docs/params.md) | Training & inference parameters |
| *Design Document* <br> [设计文档](./assets/docs/design.md) | *Framework architecture & module design* <br> 系统架构与模块设计 | | [Design Document](./assets/docs/design.md) | Framework architecture & module design |
| *Data Flow* <br> [数据流程](./assets/docs/dataflow.md) | *Data processing pipeline details* <br> 数据处理管道详解 | | [Data Flow](./assets/docs/dataflow.md) | Data processing pipeline details |
| *Model Introduction* <br> [模型介绍](./assets/docs/introduction.md) | *Model architecture & technical details* <br> 模型架构与技术细节 | | [Model Introduction](./assets/docs/introduction.md) | Model architecture & technical details |
### Download | 下载 ### Contributing
- [HuggingFace](https://huggingface.co/ViperEk/AstrAI) We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
- `python demo/download.py`
### Lincence | 许可证 1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Open a Pull Request.
- [GPL-3.0](LICENSE) For major changes, please open an issue first to discuss what you would like to change.
### Community
- **GitHub Issues**: [Issue Tracker](https://github.com/ViperEkura/AstrAI/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ViperEkura/AstrAI/discussions)
- **HuggingFace**: [Model Hub](https://huggingface.co/ViperEk/AstrAI)
### License
This project is licensed under the [GPL-3.0 License](LICENSE).
---
<div align="center">
<em>A lightweight Transformer framework designed for both high performance and ease of use.</em>
</div>

144
assets/docs/README-zh-CN.md Normal file
View File

@ -0,0 +1,144 @@
<div align="center">
<!-- <img src="../images/project_logo.png" width="auto" alt="Logo"> -->
<h1>AstrAI</h1>
<div>
<a href="../../README.md">English</a> •
<a href="#chinese">中文</a>
</div>
<p>
<strong>轻量级 Transformer 训练与推理框架</strong>
</p>
</div>
<div align="center">
<img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="python">
<img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="license">
<img src="https://img.shields.io/github/v/release/ViperEkura/AstrAI?color=76bad9" alt="release">
<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.stargazers_count&label=stars&suffix=%20stars&color=76bad9" alt="stars">
<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FViperEkura%2FAstrAI&query=%24.forks_count&label=forks&suffix=%20forks&color=76bad9" alt="forks">
</div>
<br>
<div align="center">
<a href="../../README.md">English</a> •
<a href="#chinese">中文</a> •
<a href="https://github.com/ViperEkura/AstrAI/issues">问题追踪</a> •
<a href="https://github.com/ViperEkura/AstrAI/discussions">讨论区</a> •
<a href="https://huggingface.co/ViperEk/AstrAI">HuggingFace</a>
</div>
<br>
## 📖 目录
- [特性](#特性)
- [快速开始](#快速开始)
- [文档](#文档)
- [贡献](#贡献)
- [社区](#社区)
- [许可证](#许可证)
---
<a id="chinese"></a>
## 中文
### 特性
- 🚀 **高性能**: 训练与推理双向优化，高效并行。
- 🔧 **灵活**: 支持 seq/sft/dpo 多种训练方式，可定制模型架构。
- 💡 **易用**: 简洁的 API 与丰富的示例、演示。
- 📦 **轻量**: 依赖少，部署简单。
- 🔬 **研究友好**: 模块化设计，便于实验新想法。
- 🤗 **HuggingFace 集成**: 兼容 HuggingFace 模型与数据集。
### 快速开始
#### 安装
```bash
git clone https://github.com/ViperEkura/AstrAI.git
cd AstrAI
pip install -e .
```
安装开发依赖：
```bash
pip install -e ".[dev]"
```
#### 训练模型
```bash
python tools/train.py \
--train_type=seq \
--data_root_path=/path/to/dataset \
--param_path=/path/to/param_path
```
#### 文本生成
```bash
python tools/generate.py --param_path=/path/to/param_path
```
#### 演示
查看 `demo/` 文件夹中的演示：
```bash
# 下载预处理数据（运行演示前必需）
python demo/download.py
# 交互式流式聊天
python demo/stream_chat.py
# 批量生成
python demo/generate_batch.py
# 自回归生成
python demo/generate_ar.py
```
观看 [bilibili](https://www.bilibili.com/video/BV1z5RPYHEkd) 上的视频演示。
### 文档
| 文档 | 说明 |
|------|------|
| [参数说明](./params.md) | 训练与推理参数配置 |
| [设计文档](./design.md) | 系统架构与模块设计 |
| [数据流程](./dataflow.md) | 数据处理管道详解 |
| [模型介绍](./introduction.md) | 模型架构与技术细节 |
### 贡献
我们欢迎贡献！请参阅[贡献指南](../../CONTRIBUTING.md)了解详情。
1. Fork 本仓库。
2. 创建功能分支。
3. 提交更改。
4. 发起 Pull Request。
重大更改请先开 issue 讨论。
### 社区
- **GitHub Issues**: [问题追踪](https://github.com/ViperEkura/AstrAI/issues)
- **Discussions**: [GitHub 讨论区](https://github.com/ViperEkura/AstrAI/discussions)
- **HuggingFace**: [模型中心](https://huggingface.co/ViperEk/AstrAI)
### 许可证
本项目采用 [GPL-3.0 许可证](../../LICENSE)。
---
<div align="center">
<em>专为高性能与易用性设计的轻量级 Transformer 框架。</em>
</div>