# ai-inAction

**Repository Path**: kcnf-python/ai-in-action

## Basic Information

- **Project Name**: ai-inAction
- **Description**: ai-inAction
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-inAction

AI Agent 开发学习与实践项目，通过系列示例（sample）演示基于 LangChain / LangGraph 的大模型应用开发。

## 一、技术栈总览

| 层级 | 技术 | 说明 |
|------|------|------|
| 语言与运行时 | Python 3.11 | 由根目录 [.python-version](.python-version) 单点控制 |
| 项目管理 | uv（workspace 模式） | 单一工具统一管理依赖解析、锁文件、虚拟环境与多模块 |
| LLM 应用框架 | LangChain / LangGraph | 工具调用、RAG、StateGraph 编排、ReAct Agent |
| 大模型 | DeepSeek（deepseek-chat） | 经 OpenAI 兼容协议接入，`ChatOpenAI` 统一客户端 |
| 向量数据库 | ChromaDB | 本地持久化（`./chroma_db`），充当 Agent 记忆与知识库 |
| Embedding | OpenAIEmbeddings | 默认走 DeepSeek 端点；本地 HuggingFace 模型为可选依赖 |
| 配置管理 | python-dotenv | 各模块 `.env` + `config.py` 模式，密钥不入库 |
| 版本控制 | Git / Gitee | `.gitignore` 排除 `.env`、`.venv/`、`*.sqlite3` 等 |

## 二、工程管理方式：uv workspace

全仓收敛为 **uv 单一管理体系**：根工程声明 workspace，每个示例模块独立 `pyproject.toml` 只声明自己的直接依赖，全仓共享一个 `uv.lock` 保证依赖版本一致、安装可复现。

```
ai-in-action/
├── pyproject.toml          # 根工程 + [tool.uv.workspace] members = ["sample-demo/*", "demo"]
├── uv.lock                 # 全仓唯一锁文件，覆盖全部传递依赖
├── .python-version         # Python 3.11
├── .venv/                  # uv 管理的统一虚拟环境（不入库）
├── demo/                   # 独立 demo 包（根入口示例）
│   ├── pyproject.toml
│   └── main.py
└── sample-demo/
    ├── sample-00-demo/     # 每个模块独立 pyproject.toml
    ├── sample-01-demo/
    ├── ...
    └── sample-07-demo/
```

| 管理项 | 载体 | 说明 |
|--------|------|------|
| 根工程 | [pyproject.toml](pyproject.toml) | 项目元数据 + workspace 成员声明 |
| 模块依赖 | `sample-demo/*/pyproject.toml` | 仅声明直接依赖，传递依赖由锁文件解析 |
| 依赖锁定 | [uv.lock](uv.lock) | 全仓唯一，跨模块版本强制一致 |
| Python 版本 | [.python-version](.python-version) | 单点控制，消除多版本并存 |
| 虚拟环境 | `.venv/` | uv 自动创建，已加入 .gitignore |

管理原则：

- **声明式依赖**：模块代码里 `import` 了什么，就在该模块 `pyproject.toml` 声明什么，禁止 pip freeze 式全量快照
- **单一锁文件**：所有依赖变更经 `uv add` / `uv sync` 落盘到根 `uv.lock`，不手工编辑
- **单一 Python 版本**：全仓统一由 `.python-version` 控制

## 三、日常命令

```bash
uv sync --all-packages                                   # 一次性同步全部模块环境
uv sync --package sample-01-demo                         # 只同步指定模块
uv add --package sample-01-demo langchain-chroma         # 为指定模块添加依赖（自动更新 uv.lock）
uv remove --package sample-01-demo chromadb              # 移除依赖
uv run --package sample-01-demo demo1_llm_memory_tool.py # 在模块环境中运行脚本
```

## 四、快速开始（完整运行步骤）

### 1. 安装 uv

Windows PowerShell：

```bash
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version    # 验证安装
```

Python 3.11 无需手动安装，uv 会依据根目录 `.python-version` 自动下载并管理。

### 2. 获取代码

```bash
git clone <仓库地址>
cd ai-in-action
```

### 3. 同步依赖环境

```bash
uv sync --all-packages
```

uv 会自动创建 `.venv/`，并按 `uv.lock` 安装全部模块依赖。

可选：如需运行 sample-01 的本地向量模型示例（demo2_chromadb_memory.py），额外安装：

```bash
uv sync --package sample-01-demo --extra hf-embeddings
```

### 4. 配置模型密钥

在要运行的模块目录下创建 `.env` 文件（如 `sample-demo/sample-01-demo/.env`）：

```dotenv
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
```

`.env` 已被 [.gitignore](.gitignore) 排除，不会提交入库；密钥缺失时脚本启动即报错提示。

### 5. 运行示例

```bash
# 根入口示例（独立 demo 包）
uv run --package demo main.py

# 环境自检：验证 langchain / langgraph / mcp / chromadb / openai 可导入
uv run --package sample-00-demo check_env.py
```

运行各学习示例（含 `chroma_db`、`knowledge.txt` 等相对路径读写的示例，需先进入模块目录）：

```bash
cd sample-demo/sample-01-demo
uv run --package sample-01-demo demo1_llm_memory_tool.py
```

按编号递进学习：00 环境自检 → 01 记忆与工具 → 02 LLM 基础 → 03 工具系统 → 04 RAG 知识库 → 05 规划模式 → 06/07 ReAct Agent。

> 注意：运行 RAG / 向量记忆类示例后，模块目录会生成 `chroma_db/` 本地向量库（已在 .gitignore 排除），删除该目录即可重建知识库。

## 五、历史说明

项目早期采用「根工程 uv + 示例模块 conda/pip」混合管理（environment.yml + pip freeze 式 requirements.txt），现已全部迁移至 uv workspace，conda 体系退出。若未来引入 GPU 推理等编译型二进制依赖需求，再评估 conda / pixi。