从 RAG 的基本原理讲起，完整记录 uv 包管理工具的安装与镜像配置、项目基本包结构搭建、公共类代码导入与首次 Git 提交。

本篇要点

  • 理解 RAG 的基本流程，明确项目为什么用 RAG
  • 掌握 uv 的安装、镜像配置、项目初始化与依赖同步
  • 搭建项目的基本包结构，导入项目公共类代码
  • 把项目交给 git 管理并完成第一次提交

内容回顾

1、为什么使用 RAG

  • 现在模型的上下文窗口已经巨大了，但每次真的使用都会消耗 token；塞进去过多的内容，回答反而不准确了。
  • 模型在某些方面有知识欠缺，不会也答（幻觉）。

2、RAG 的两条链路

  • 准备：各种数据文件 -> text -> 嵌入式模型 -> 向量 -> 向量数据库
  • 检索：用户提问 -> 嵌入式模型 -> 向量 -> 相似度 -> chunk -> 问题 + 上下文 -> 提示词 -> LLM -> 结果
1
2
3
4
5
准备   各种数据文件 -> text -> 嵌入式模型 -> 向量 -> 向量数据库
                                                       |
检索   用户 -> 提问 -> 嵌入式模型 -> 向量 - 相似度 --
         |                                        |
        结果 <- LLM <- 提示词 <- 问题+上下文 <- chunk <-
  • 掌柜智库项目的整条流程，就是这条 RAG 流程的工程化扩展：准备阶段 7 个节点、检索阶段 7 个节点，后面每天实现其中一部分。

今天内容

1、使用 uv 管理我们的项目

1.1 安装 uv

两种方式：

  • 25+ 的 pycharm -> new project -> uv 即可【安装 uv 包管理工具 | 创建一个项目使用 uv 管理】
  • 使用命令安装：
1
2
3
pip install uv
pip show uv        # 查看 uv 安装路径 -> 把该路径加入环境变量 path
uv --version

1.2 uv 配置镜像

全局配置： 在 C:\Users\登录用户名\AppData\Roaming\uv 下创建 uv.toml：

1
2
3
4
# 配置默认的 PyPI 镜像源 (清华源)
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

局部配置： 使用 uv 管理的项目，写在 pyproject.toml 里 -> 包信息 | 配置镜像：

1
2
3
4
5
# 项目下配置环境变量(更推荐)
[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

局部配置放在项目里、跟着项目走，更推荐这种方式。

1.3 创建使用 uv 管理的项目和创建虚拟环境

IDE 方式：

  • 25+ pycharm + 直接 new project - uv【安装 uv、使用 uv 管理项目、自动创建 .venv 虚拟环境】

命令方式：

  1. 初始化 uv 管理的项目：
1
uv init ai_班级号_knowledge_base --bare      # 纯净版本

然后 使用 pycharm - open - 打开 -> pyproject.toml【项目描述和依赖信息以及镜像配置文件】。

  1. 24 版本有问题 -> 没有创建 .venv 虚拟环境，使用 uv 创建虚拟环境：
1
2
uv venv --python=3.11      # 或者 3.12
# 创建虚拟环境 .venv [python.exe(3.11 / 3.12) + 依赖信息]

坑： python 解释器版本 3.09 / 3.10 / 3.11 / 3.12 / 3.13 / 3.14 都要注意 path 变量，解释器选错后面导入会直接报错。

  1. pycharm 手动指定解释器：右下角 -> intercepters settings -> add intercepter -> add local intercepter。

激活当前虚拟环境：

1
./.venv/Scripts/activate.bat

在 pycharm 的命令窗口前面显示 (项目名)，就算激活了。

  1. 如果在 pycharm 中，使用 uv 命令报错，就切换 pycharm 中的命令工具：file - setting -> Terminal，切换 cmd 或者 power shell。

这一步的完整流程小结：

1
2
3
4
安装 uv -> 配置镜像
        -> uv init 项目名 --bare         (uv 管理的项目)
        -> uv venv --python=3.11 / 3.12  (创建 / 配置虚拟环境)
        -> pycharm 指定解释器位置

提示： 命令行前面如果出现 (base) (项目名) x.x.x.x，说明 conda 的 base 环境还激活着，用 conda deactivate 取消。

1.4 同步项目依赖

需要共享两个文件：

  • pyproject.toml -> 项目信息、依赖信息（很多都不是固定的版本，是范围版本）、镜像信息
  • uv.lock -> 记录下载时刻的具体版本，作用是避免依赖同步版本漂移！
1
uv sync

uv sync 想要同步所有依赖配置（下载）时，会先检查 pyproject.toml 的依赖信息（范围版本），再检查 uv.lock 中具体的版本，最后进行下载。

同步项目配置的步骤：

  1. 找到 掌柜智库 / 资料 / 依赖配置 这 2 个文件
  2. 粘贴到当前项目下，适当修改项目基本信息（项目名）
  3. 执行 uv sync 进行依赖同步
  4. 校验：uv tree 看见依赖树
  5. 校验：创建 xx.py，写 from langchain ... 能导入成功（导入失败一般是解释器选择的不对）

1.5 uv 包管理说明

  • 兼容 pip： uv pip 安装的包不会记录到 pyproject.toml 中，适合临时测试的包；uv pip 的命令都是兼容的【保留你的习惯，兼容 uv 的速度】。
1
uv pip install xxx
  • uv 自己的方式：
1
2
uv add 依赖=xx
uv remove 依赖

2、搭建项目的基本架构

2.1 搭建项目的基本包结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
项目名文件夹
├── .venv                  虚拟环境文件夹
├── pyproject.toml
├── uv.lock
├── .env                   项目配置 / 模型配置 / 数据库连接参数 …  API_KEY = xxx
├── .env.example           告诉对方我们有哪些 key（key 没有值）  API_KEY=输入你的模型key
├── .gitignore             忽略文件
├── app                    开发代码，保证代码结构清晰和复用
│   ├── utils / shared     工具模块【原则上说不需要我们写!! minio、mongodb、milvus】
│   ├── process            langgraph 的节点
│   │   ├── import_
│   │   └── query
│   ├── rag                rag 项目的核心业务代码
│   │   ├── import_
│   │   └── query
│   ├── resources          提示词 / 页面文件 .html 等静态资源（普通的文件夹、目录）
│   ├── api                对外的接口 fastapi
│   │   ├── http           接口
│   │   └── schema         数据类型 …
│   └── infra              公共出口，集成了 shared 下面的使用!!（shared 是个模型 py -> llm_providers . 函数）
└── tests                  测试代码

说明：

  • process 放 langgraph 的节点，rag 放核心业务代码，两者都按 import_ / query 分目录，和项目”准备 / 检索”两条链路一一对应。
  • api 分成 http（接口）和 schema（数据类型）；infra 是对外统一的公共出口。
  • utils / shared 是工具模块，像 minio、mongodb、milvus 这些原则上不需要我们自己写。

2.2 导入项目的公共类代码

  • 2.2.1 配置文件 .env / .env.sample
  • 2.2.2 日志文件 shared / runtime / logger.py【日志级别 / 日志配置 / 动态参数 / 装饰器 node_log、step_log】
  • 2.2.3 配置加载类 config …、mcp_config …、common -> load_env(override=True)
  • 2.2.4 其他的 shared / doc
  • 2.2.5 封装了一个公共类 infra / config / providers / InfraConfig -> 包容了 8 个配置类，属性写法：类型 = Field(default_factory=lambda: xxx)
1
2
# InfraConfig 中的属性写法示意
属性: 类型 = Field(default_factory=lambda: xxx)

这些公共类代码直接拿来用即可，重点是先把”配置、日志、工具”这三块能力接进项目。

2.3 项目代码提交到 git

  1. 下载一个忽略文件插件（它可以帮我们创建一个带有完整忽略内容的忽略文件）：file / settings / plugins / .ignore
  2. 创建忽略文件：项目 -> 右键 -> new file -> ignore file -> Git -> python 项目 -> 生成
1
2
3
logs/
doc/
tests/
  1. 项目被 git 管理 / 并且完成第一次提交

2.4 打开进度统计

  • 每个人按组 / 2 个