268 lines
15 KiB
Markdown
Executable File
268 lines
15 KiB
Markdown
Executable File
# 阶段一 · 小点 8：软件工程与基础设施
|
||
|
||
> 所属：阶段一 前置核心基础（必备打底）
|
||
> 定位：Agent 不是"只要模型会答就行"的玩具，它是要落地、要被人 review、要跑几个月不出乱的工程。这一节补上 Git、API、容器、数据库这四根"工程地基"。
|
||
|
||
## 精简大纲
|
||
|
||
1. 版本控制：Git 进阶（rebase / cherry-pick）、分支流规范
|
||
2. API 开发：FastAPI、RESTful、SSE 流式、WebSocket
|
||
3. 容器化：Docker、Dockerfile 分层优化、Docker Compose
|
||
4. 数据库基础：PostgreSQL / MySQL / Redis / MongoDB
|
||
|
||
## 学习内容详情
|
||
|
||
### 1. 版本控制（Git 进阶）
|
||
|
||
#### 1.1 merge 与 rebase 的区别
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[功能分支开发完] --> B{合并方式}
|
||
B -->|merge| C[产生一个新的合并提交, 历史有分叉]
|
||
B -->|rebase| D[把提交搬到主分支顶端, 历史线性更清爽]
|
||
```
|
||
|
||
- **rebase（变基）**：把当前分支提交"搬到"目标分支顶端，保持线性历史；merge 产生分叉。
|
||
- **cherry-pick**：摘取某一个 commit 到当前分支——线上 bug 修在 dev 后，只把修复提交摘给 prod，不把一堆无关提交带上。
|
||
|
||
```bash
|
||
# cherry-pick 典型场景
|
||
git checkout prod # 切到生产分支
|
||
git cherry-pick <commit-hash> # 只把某个修复提交应用过来
|
||
git push origin prod
|
||
```
|
||
|
||
- **分支流（dev / test / prod）**：环境与分支一一对应；**分支保护规则（禁直推 prod）**是协作底线。
|
||
|
||
```
|
||
开发流程:
|
||
feature/x ──merge──▶ dev ──实测──▶ test ──发布──▶ prod
|
||
你自己 CI/CD 自动 (受保护, 禁直推)
|
||
```
|
||
|
||
### 2. FastAPI API 开发
|
||
|
||
#### 2.1 为什么 Agent 服务要用 FastAPI
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[Agent 服务] --> B[POST /chat 普通问答]
|
||
A --> C[GET /tasks/id 查任务状态]
|
||
A --> D[GET /chat/stream SSE 流式]
|
||
A --> E[WS /realtime WebSocket 双向]
|
||
B --> F[RESTful 资源风格]
|
||
D --> G[单向输出·逐token]
|
||
E --> H[双向·语音/协作编辑]
|
||
```
|
||
|
||
- **RESTful**：以资源为中心的接口风格；对照 Agent 服务：POST /chat、GET /tasks/{id}。
|
||
- **路由**：按资源分文件组织，别全堆在 main.py。
|
||
- **依赖注入（DI）**：`Depends` 机制，全局共享资源（LLM client / 存储连接），测试时可替换成 mock。
|
||
- **SSE vs WebSocket 选型**：单向输出（Agent 逐 token 回答）用 **SSE**；双向实时交互（语音 / 协作编辑）才用 **WebSocket**。绝大多数 Agent 场景 SSE 就够。
|
||
|
||
> 🔬 **深度理解 · SSE 与 WebSocket（流式传输选型）**：
|
||
> 1. **本质**：SSE（Server-Sent Events）是"服务端 → 客户端"的单向文本事件流，基于 HTTP 长连接；WebSocket 是"双向全双工"的长连接帧协议，两者满足不同需求。
|
||
> 2. **机制**：SSE 复用 HTTP，服务端持续写 `data: ...\n\n` 事件，天然易解析、支持自动重连、无跨域握手改造成本；WebSocket 需先握手升级（http→ws）再双向收发文本/二进制帧，连接更"重"但能力更强。
|
||
> 3. **为什么重要**：Agent 逐 token 打字机输出是"单向推送给用户"，SSE 恰好够用且实现最简；只有语音实时对话、协作编辑等需要"双向实时"才上 WebSocket。选错会白白增加复杂度。
|
||
> 4. **易错点**：SSE 是单向的（客户端不能跟服务器并行上行对流），需要双向就别硬套 SSE；WebSocket 要做心跳保活与断线重连，生产成本更高。
|
||
|
||
```python
|
||
# main.py —— 一个带 SSE 流式的 Agent 接口
|
||
import asyncio
|
||
import json
|
||
from fastapi import FastAPI, Depends
|
||
from fastapi.responses import StreamingResponse
|
||
|
||
app = FastAPI(title="Agent 服务")
|
||
|
||
# 依赖注入: 全局共享资源(例: LLM client), 可在测试时替换成 mock
|
||
def get_llm_client():
|
||
# 返回一个模型客户端(这里简化)
|
||
return {"model": "gpt-4o"}
|
||
|
||
@app.post("/chat")
|
||
async def chat(payload: dict, client: dict = Depends(get_llm_client)):
|
||
# RESTful: 资源是"聊天", 方法是 POST
|
||
return {"reply": "这是普通(非流式)回复"}
|
||
|
||
@app.get("/chat/stream")
|
||
async def stream_chat(llm=Depends(get_llm_client)):
|
||
"""SSE 流式接口: 逐 token 推给前端打字机渲染"""
|
||
async def event_stream():
|
||
for word in ["你好", "，", "我是", "AI", "助手"]:
|
||
yield f"data: {json.dumps({'token': word}, ensure_ascii=False)}\n\n"
|
||
await asyncio.sleep(0.1) # 模拟模型逐字生成
|
||
yield "data: [DONE]\n\n" # 结束标记
|
||
|
||
return StreamingResponse(event_stream(), media_type="text/event-stream")
|
||
```
|
||
|
||
- **响应模型**：用 `response_model=ChatResponse` 约束输出结构，自动生成 swagger 文档；请求非法自动返回 422。
|
||
|
||
```python
|
||
from pydantic import BaseModel
|
||
|
||
class ChatResponse(BaseModel):
|
||
reply: str
|
||
used_tokens: int
|
||
|
||
@app.post("/chat2", response_model=ChatResponse)
|
||
async def chat2(payload: dict):
|
||
return ChatResponse(reply="结构化响应", used_tokens=123)
|
||
```
|
||
|
||
- **运行**：`uvicorn main:app --reload --port 8000`。
|
||
|
||
### 3. 容器化（Docker / Compose）
|
||
|
||
#### 3.1 镜像分层：把"装依赖"放"拷代码"之前
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[FROM python:3.12] --> B[COPY requirements 先拷贝依赖清单]
|
||
B --> C[RUN pip install 安装依赖 → 形成缓存层]
|
||
C --> D[COPY . 最后才拷源码]
|
||
D --> E[改代码时常命中缓存, 不用重装依赖 → 更小更快]
|
||
```
|
||
|
||
- **Dockerfile 多阶段构建**：先装依赖（命中缓存层）再拷源码，镜像更小。
|
||
- **镜像分层**：把"装依赖"放"拷代码"之前，改代码时命中缓存不必重装依赖。
|
||
- **docker-compose.yml**：本地一键拉起"应用 + Redis + 向量库"整套环境。
|
||
- ⚠️ 不用 `docker commit` 造镜像（不可复现），一律用 Dockerfile / Compose 声明式定义。
|
||
|
||
> 🔬 **深度理解 · Docker 镜像分层与构建缓存**：
|
||
> 1. **本质**：镜像由若干只读层叠加而成，每条 `RUN/COPY/ADD` 指令生成一层（含该层的内容 diff 与元数据）；构建时若某层输入未变，直接复用缓存而不重算。
|
||
> 2. **机制**：Docker 以"指令内容 + 当前父层镜像内容"作为缓存键。先 `COPY requirements.txt` + `RUN pip install`，再 `COPY .`——这样改业务代码时依赖层缓存命中、装依赖被跳过，迭代构建又快又省。
|
||
> 3. **为什么重要**：依赖安装往往最耗时（网络拉取 / 编译），把这层前移可让"改代码→重建"的迭代秒级完成；层组织也直接影响镜像体积与传输成本。
|
||
> 4. **易错点**：若把 `COPY .` 放到前面，任何源码改动都会让后续所有层缓存失效、依赖被迫重装；`docker commit` 生成的是基于运行态的黑盒镜像、不可复现，故生产一律用 Dockerfile 声明式构建。
|
||
|
||
```dockerfile
|
||
# Dockerfile —— 多阶段构建, 镜像更小更安全
|
||
FROM python:3.12-slim AS base
|
||
|
||
WORKDIR /app
|
||
# ① 先拷依赖清单并安装 → 命中缓存
|
||
COPY requirements.txt .
|
||
RUN pip install --no-cache-dir -r requirements.txt
|
||
|
||
# ② 最后才拷源码 → 改代码不动前面的缓存层
|
||
COPY . .
|
||
|
||
# 非流式/流式都从这里启
|
||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||
```
|
||
|
||
```yaml
|
||
# docker-compose.yml —— 一键拉起整套依赖
|
||
# version: "3.9" 新版 Compose 已弃用/忽略该字段, 省略即可, 此处仅注释说明
|
||
services:
|
||
app:
|
||
build: .
|
||
ports: ["8000:8000"]
|
||
environment:
|
||
REDIS_URL: redis://redis:6379
|
||
VECTOR_HOST: qdrant:6333
|
||
depends_on: # 等 redis/向量库起来再启动应用
|
||
- redis
|
||
redis:
|
||
image: redis:7
|
||
qdrant:
|
||
image: qdrant/qdrant # 向量数据库示例
|
||
```
|
||
|
||
### 4. 数据库基础
|
||
|
||
#### 4.1 选型速查
|
||
|
||
| 场景 | 数据库 | 关键点 |
|
||
|-|-|-|
|
||
| 结构化业务数据 / 任务元数据 | PostgreSQL / MySQL | SQL、表设计、事务 |
|
||
| 会话缓存 / 临时状态 | Redis | 内存 + TTL 过期 |
|
||
| 非结构化记忆 / 对话历史 | MongoDB | 文档存储、灵活 schema |
|
||
|
||
> ⏳ **短期可不深究**：MongoDB 的文档存储、灵活 schema、聚合管道等细节属于"非结构化记忆"这条补充线的进阶内容，第一遍只需记住"结构化业务用 SQL 库、临时缓存用 Redis、对话/记忆可用文档库"的分工即可，真接 MongoDB 时再深学。
|
||
|
||
```python
|
||
# Redis TTL: 会话 30 分钟无活动自动过期, 清理僵尸会话
|
||
import redis
|
||
r = redis.Redis(host="localhost", port=6379)
|
||
|
||
r.setex("session:abc123", timeout=1800, value="会话数据")
|
||
# ↑ setex: 设一个 1800 秒(30分钟)后自动过期的 key
|
||
print(r.get("session:abc123")) # 存在期内能读到
|
||
# 30 分钟后: r.get(...) 返回 None, 已被自动清理
|
||
```
|
||
|
||
```python
|
||
# PostgreSQL 事务: "写任务+写明细"两张表必须包事务, 要么全成要么全回滚
|
||
from sqlalchemy import create_engine, text
|
||
from sqlalchemy.orm import sessionmaker
|
||
|
||
engine = create_engine("postgresql://user:pwd@localhost/agentdb")
|
||
Session = sessionmaker(bind=engine)
|
||
db = Session()
|
||
|
||
try:
|
||
db.execute(text("INSERT INTO tasks(...) VALUES(...)")) # 1) 写主任务（SQLAlchemy 2.x 裸 SQL 须用 text() 包裹）
|
||
db.execute(text("INSERT INTO task_items(...) VALUES(...)")) # 2) 写明细
|
||
db.commit() # 两步都成功才一起提交
|
||
except Exception:
|
||
db.rollback() # 任一步失败, 全部回滚, 不留半截脏数据
|
||
raise
|
||
finally:
|
||
db.close()
|
||
```
|
||
|
||
> **一句话原则**：凡是涉及"要一起变才有效"的多条写入（如任务 + 明细、账户 + 流水），必须包事务。Redis 适合可重建的临时缓存，不适合存需要强一致的核心业务。
|
||
|
||
> 🔬 **深度理解 · 数据库事务（ACID 与原子性）**：
|
||
> 1. **本质**：事务把"多条要一起成功才有效"的写入打包成原子操作——要么全提交，要么全回滚，杜绝"只写了一半"的中间态脏数据。
|
||
> 2. **机制**：围绕 ACID（原子性 / 一致性 / 隔离性 / 持久性）。实现上靠日志与锁 / 多版本并发控制（MVCC）：出错时按 undo 日志回滚已写部分；并发事务用隔离级别防止读到彼此的中间状态。
|
||
> 3. **为什么重要**：Agent 的"任务 + 明细"、"账户 + 流水"这类强关联多写，少了事务会出现半截数据、账实不符；这正是关系库相对内存缓存的核心价值。
|
||
> 4. **易错点**：写操作在 `commit` 前一旦中途异常必须 `rollback`（别忘了 finally 里关闭会话）；隔离级别选错会引入脏读 / 不可重复读；事务别包过长的耗时调用，长时间持锁会拖垮并发吞吐。
|
||
|
||
## 本节自检
|
||
|
||
- [ ] 能用 FastAPI 实现一个带 SSE 流式的接口并跑通
|
||
- [ ] 能编写多阶段 Dockerfile 并 compose 拉起应用 + Redis + 向量库
|
||
- [ ] 会用 Redis TTL 与 PostgreSQL 事务
|
||
- [ ] 能说清 merge vs rebase、以及何时用 cherry-pick
|
||
|
||
## 本节配套思考题（快速入门的检验）
|
||
|
||
1. merge 和 rebase 各产生什么形态的提交历史？在多人协作的共享分支上你会更偏好哪种？
|
||
2. "逐 token 回答"用 SSE，"语音实时对话"用 WebSocket，判断依据是什么？
|
||
3. 为什么 Dockerfile 要"先拷依赖再拷源码"？顺序反了会损失什么？
|
||
4. 任务表和它对应的明细表为什么要统一包在一个事务里？
|
||
|
||
## 本节常见面试题（深度解析）
|
||
|
||
> 针对本节核心知识的面试高频点，配合"本质+机制"式理解，能让你答得既有深度又有广度。
|
||
|
||
### 面试题 1：merge 和 rebase 各产生什么形态的提交历史？在多人共享分支上你会更偏好哪种？
|
||
- **面试官想考察**：是否理解 Git 两种整合方式的语义差异与协作风险，而非只背名词。
|
||
- **专业作答（含深度）**：
|
||
1. **merge**：把另一分支并入当前，生成一个"合并提交"，保留双方分叉点，历史呈网状、保留真实发生过的并行路径。
|
||
2. **rebase**：把当前分支的提交"搬到"目标分支顶端并重写这些提交（新的哈希），历史线性清爽，便于 review 与主分支快进。
|
||
3. **取舍**：rebase/GitLab merge 更整洁但**改写了提交哈希**，在已共享/已推送的分支上 rebase 会破坏他人历史引用，造成混乱；merge 更安全保守但历史分叉多。
|
||
4. **实践建议**：主分支（dev/test/prod）与多人共享分支上不要随意 rebase、用 merge 保护历史；个人功能分支（feature）在合入前可用 rebase 压平到最新主线以保持整洁。
|
||
- **加分亮点 / 深度追问**：可提"rebase 与 merge 时冲突解决的差异（rebase 逐个提交重放、冲突也要逐个解）"，以及 `git pull --rebase` 与 `rerere`（自动记录冲突解法）等进阶技巧。
|
||
|
||
### 面试题 2："逐 token 回答"用 SSE、"语音实时对话"用 WebSocket，判断依据是什么？
|
||
- **面试官想考察**：能否把"单向 vs 双向"这一本质应用到传输选型，而非背协议名。
|
||
- **专业作答（含深度）**：
|
||
1. **本质区分**：SSE 是服务端→客户端的单向事件流（基于 HTTP）；WebSocket 是双向全双工长连接。
|
||
2. **判断依据**：先问"这个场景需不需要客户端在连接期主动上行？"——Agent 打字机只需服务端单向推送 → SSE 够用且简单；语音对话/协作编辑要双向实时收发 → WebSocket。
|
||
3. **成本对比**：SSE 复用 HTTP、易解析、自动重连、实现轻；WebSocket 要握手升级、心跳保活、断线重连，生产成本更高，只在确有双向需求时用。
|
||
4. **结论**：绝大多数 Agent 场景是"单向推 token"，SSE 是性价比最优解。
|
||
- **加分亮点 / 深度追问**：可提"SSE 也能在一条长连接上携带多字段事件（结构化事件名 + data）"，以及 WebSocket 上的二进制流（语音帧）为何比文本流更适合实时交互的细节。
|
||
|
||
### 面试题 3：为什么 Dockerfile 要先"拷依赖再拷源码"？把顺序反过来会损失什么？
|
||
- **面试官想考察**：是否理解镜像分层缓存机制，能否推导出"层顺序影响构建缓存命中"。
|
||
- **专业作答（含深度）**：
|
||
1. **分层缓存原理**：每层以"指令 + 父层内容"做缓存键，命中即复用。
|
||
2. **先装依赖**：依赖清单（requirements）变动频率远低于源码，先 `COPY requirements` + `RUN pip install` 形成稳定的依赖层；改源码只重建后面的层，秒级迭代。
|
||
3. **反序的损失**：若先 `COPY .`，任何一行源码改动都会让整个缓存失效，依赖被迫全部重装（最耗时部分白跑），构建极其缓慢。
|
||
4. **延伸**：这也说明应把"爱变的内容放后面、稳定内容放前面"，并避免用 `docker commit` 这类不可复现的黑盒方式造镜像。
|
||
- **加分亮点 / 深度追问**：可提 `.dockerignore`（排除 node_modules/.git 等避免无效缓存失效）、多阶段构建（仅把运行时依赖带入最终镜像压缩体积）这两个进阶优化。 |