---
title: General Deep Learning
emoji: 🏃
colorFrom: yellow
colorTo: gray
sdk: gradio
sdk_version: 6.12.0
python_version: 3.12
app_file: app.py
pinned: false
license: mit
short_description: General Deep Learning is a practical deep learning experimen
---

# 通用深度学习（General Deep Learning）

## 项目简介

**通用深度学习（General Deep Learning）** 是一个面向学习和实践的深度学习项目集合。

这个项目通过一组可运行的深度学习任务，串起数据处理、模型搭建、训练、推理和部署等常见流程。每个任务都尽量保持清晰、可修改，方便用来学习、实验和复用。

### 这个项目关注什么

- **任务完整**：每个任务尽量覆盖数据准备、模型训练、测试、导出和推理。
- **结构清晰**：把数据集、模型、训练流程和界面展示拆开，方便单独阅读和替换。
- **便于改动**：适合用来尝试新数据集、新模型结构，或者把已有任务改成自己的实验。
- **保留工程细节**：包含检查点、TensorBoard、环境配置、Hugging Face Space 部署等常见实践。

### 项目内容

部分组件会采用轻量实现来帮助理解结构，部分任务也会借助 Keras、TensorFlow、keras_hub 等工具来保证流程清楚、容易跑通。

**已包含任务**：
- Wiki GPT - 基于中文维基语料的文本生成
- 诗歌生成器 - GPT 和 RNN 双版本对比
- 猫狗图片分类 - 基于 CNN 的图像分类
- Oxford Pets 图像分割 - 语义分割任务
- YOLO 目标检测 - 基于 YOLO 的单阶段目标检测

## 在线体验

[![Hugging Face Space](https://img.shields.io/badge/🤗-Hugging%20Face%20Space-blue)](https://huggingface.co/spaces/yetrun/general-deep-learning)

如果暂时不想配置本地环境，可以先访问 Hugging Face Space 体验已经导出的模型：

- [点击访问 Hugging Face Space](https://huggingface.co/spaces/yetrun/general-deep-learning)

## 文档教程

如果你想快速跑通、修改数据源、替换模型或接入新任务，请阅读：

- [使用教程](docs/tutorial.md)

如果你想理解项目结构和定位，请阅读：

- [项目架构说明](docs/architecture.md)
- [项目定位与框架比较](docs/comparison.md)

## 本地开发

### Conda 环境使用

使用方法：
```bash
# 创建环境
conda env create -f <environment.yml>
# 激活环境
conda activate general-dl
# 更新 environment.yml
conda env update -f <environment.yml> --prune
```

上述 `<environment.yml>` 是环境配置文件的路径，需要替换成实际的文件名：

- 如果你是本地开发，使用 `environment.yml`（Mac Intel 64 环境，`ENV=development`，可短写为 `ENV=dev`）
- 如果你是在远程服务器或正式训练环境上运行，使用 `environment-linux.yml`（Linux 服务器环境，`ENV=production`，可短写为 `ENV=prod`）

Mac Intel 本地环境需要注意 Keras 版本范围：

- Keras 需要大于 3.6，否则加载 `embedding(x, reverse=True)` 生成的计算图会有问题。
- Keras 需要小于 3.13，否则 RNN 训练中使用内置 `accuracy` 指标时可能遇到 TensorFlow C++ 断言失败。

> **插曲：**
> 
> 环境配置出现了问题，强制重新安装 tensorflow-text 才修复。
> 
> ```bash
> pip uninstall tensorflow-text -y
> pip install --no-cache-dir --force-reinstall tensorflow-text==2.20.0
> ```

### Conda 环境变量

首先，不同的按照环境对应不同的环境变量（`environment.yml` / `environments-linux.yml`），上文提过。

其次，为某个环境永久设置环境变量的方式：

```bash
conda env config vars set ENV=development

# 还需要重新激活
conda deactivate
conda activate general-dl
```

最后，如果你只是想临时在当前命令前使用：

```bash
ENV=dev python your_script.py
ENV=prod python your_script.py
```

### 开发工具配置

#### TensorBoard 说明

训练时，调用 `tensorboard --logdir=<logdir>` 来启动 TensorBoard，默认访问地址是 http://localhost:6006/.

`<logdir>` 通常是 `local/tasks/<project_name>/tensorboard`.

> 冷知识：tensorboard 中的代数与我们常规认为的代数不一致，第一代的计数是 0.

#### JetBrains 远程开发配置

配置本地代码映射：

1. 菜单栏：Tools → Deployment → Configuration
2. 配置目录映射：切换到Mappings标签页，Deployment path 设置远程目录路径
3. 配置排除目录，一般可排除的本地目录包括：`data/dev`, `local`, `test`.

手工同步：

- 右键文件/目录 → Deployment → Upload to...

## 部署说明

本项目已配置为 Hugging Face Space 兼容格式。如果需要更新在线体验，可以按下面的方式推送：

```bash
# 1. 在 Hugging Face 创建新的 Space（选择 Gradio SDK）
# 2. 绑定 Space 远程仓库
git remote add huggingface https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
# 3. 确保依赖同步（生成 requirements.txt）
python3 generate_requirements.py
# 4. 提交并推送
git push huggingface master
```