LazyLLM教程 | 第4讲：RAG项目工程化入门：从脚本走向模块化与可维护性

一个项目如果代码不规范会导致可读性差、维护困难、容易引入 Bug，并降低代码的可扩展性和一致性。在团队协作中，不统一的风格会增加合并冲突，影响开发效率。此外，代码不规范可能导致测试困难，影响 CI/CD 流程，甚至带来安全隐患。

本教程将带你从0开始，将一个简单的 Python 脚本逐步演化为规范的工程项目，涵盖 Git版本管理、代码规范检查、单元测试、CI/CD、文档管理，以及打包发布等关键环节。

1. 代码管理：从零开始搭建 Git 项目

1.1 什么是`Git`

Git 是一个分布式版本控制系统，用于跟踪文件的更改，特别适用于软件开发。它允许多个开发者协作开发代码，同时保留所有更改的历史记录。详述

1.2 为什么要使用 Git

代码历史可追溯，支持版本回滚
支持多人协作，提高团队效率
便于分支管理，降低开发冲突
可托管到 github gitlab等，方便备份与共享

1.3 创建一个GitHub项目

首先你要有一个 GitHub 账号，如果没有的话请先注册
登陆账号，创建一个项目（New repository）例如：my-project
只需要输入项目名称 (Repository name) 即可，项目描述（Description）选填。Public 是公开，可以在 GitHub 搜到，Private 是私密项目，只有自己和项目成员能看到。点击 Create repository

1.4 初始化 Git 仓库并推送到 GitHub

在 GitHub 上创建一个新的项目仓库（Repository）。
准备好提交代码需要的 token 创建教程
在本地初始化 Git 仓库并推送代码：

>>> mkdir my-project && cd my-project
>>> echo "# test" >> README.md
>>> git init

# 首次使用需要设置用户名和邮箱
>>> git config --global user.name "你的用户名"
>>> git config --global user.email "你的邮箱"

>>> git add README.md
>>> git commit -m "test"
>>> git branch -M main
>>> git remote add origin <your-repo-url>
>>> git push -u origin main

输入用户名及token 即可推到远程仓库

>>> git push -u origin main
Username for 'https://github.com': lwj-st
Password for 'https://lwj-st@github.com': 
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 223 bytes | 223.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/lwj-st/my-project.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

1.5 添加基本的工程文件

README.md介绍项目用途，示例：

# my-project

## 介绍
这是一个示例 Python 项目，支持自动化测试、Docker 部署，并符合 PEP 8 代码规范。

## 安装
pip install my-project

.gitignore忽略不需要提交的文件，如编译生成的二进制文件、日志文件等规则示例：

        __pycache__
        *.pyc
        test/
        dist/
        tmp/
        .vscode
        build
        *.lock
        *.db

requirements.txt记录项目依赖示例：

        lazyllm

Dockerfile：镜像构建文件 📃 创建并推送镜像
setup.py：打包与发布文件 📃 使用 setuptools 进行打包

1.6 添加主项目文件

项目代码以【第2讲：10分钟上手一个最小可用RAG系统】为例，添加主代码文件

my_project/retriever.py

from lazyllm import Retriever, Document

def create_retriever(path: str, query: str):
    """
    创建并执行检索

    Args:
        path (str): 文档的绝对路径
        query (str): 查询语句

    Returns:
        list: 检索结果
    """
    doc = Document(path)
    retriever = Retriever(doc, group_name="CoarseChunk", similarity="bm25_chinese", topk=3)
    return retriever(query)

my_project/__init__.py

from .retriever import create_retriever

__version__ = '0.1.0'
__all__ = ['create_retriever']

2. 版本管理和分支策略

良好的分支管理策略有助于多人协作和稳定版本发布。

2.1 常见分支命名

主分支（main）：始终保持稳定可发布状态
开发分支（dev）：用于日常开发
功能分支（feature/*）：用于开发新功能，完成后合并回 dev
修复分支（hotfix/*）：用于紧急修复生产环境 bug

2.2 Git 分支管理操作示例

# 创建并切换到开发分支
>>> git checkout -b dev

# 在dev分支上新创建功能分支
>>> git checkout -b feature/new-feature

...修改代码...

>>> git add .
>>> git commit -m "Add new feature"
>>> git push origin feature/new-feature

# 开发完成后合并回 dev
>>> git checkout dev

>>> git merge feature/new-feature
>>> git push origin dev

2.3 在github上提交pull request

当改好的代码提到远程仓库后就可以提交pull request了
进入 GitHub 仓库主页，点击 "Pull Requests" -> "New Pull Request"
如果是同一仓库的Pull Requests 选择对应的 base （目标分支） 和 compare （比对分支）即可
如果是fork仓库的Pull Requests 则有 base repository （目标仓库）和 base （目标分支）默认是fork的源仓库信息，head repository （源仓库）和 compare （比对分支）默认是自己仓库的信息
添加 PR 说明，点击 "Create Pull Request"