Python AI 入门避坑指南

# Python 3.10+ 的模式匹配
def process_data(data):
    match data:
        case {"type": "text", "content": text}:
            return text.upper()
        case {"type": "number", "value": n}:
            return n * 2
        case _:
            return "未知类型"

二、数据处理：NumPy 与 Pandas 的坑

2.1 NumPy 的广播机制

广播（Broadcasting）是 NumPy 强大的特性，也是初学者最容易踩坑的地方：

import numpy as np
# 正常理解
a = np.array([1, 2, 3])
b = np.array([10])
print(a + b)  # [11, 12, 13]，符合预期
# 广播的陷阱
a = np.array([[1, 2, 3], [4, 5, 6]])  # shape: (2, 3)
b = np.array([1, 2])  # shape: (2,)
print(a + b)  # 报错！形状不匹配
# 正确做法
b = b.reshape(2, 1)  # shape: (2, 1)
print(a + b)  # 正确广播

记忆技巧：广播从右向左比较维度，要么相等，要么其中一个为 1。

2.2 Pandas 的索引陷阱

import pandas as pd
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'score': [85, 90, 78]
})
# 坑点一：链式索引可能导致 SettingWithCopyWarning
df[df['score'] > 80]['name'] = 'Excellent'  # 警告！不会生效
# 正确做法
df.loc[df['score'] > 80, 'name'] = 'Excellent'
# 坑点二：索引不是列
print(df.columns)  # Index(['name', 'score'], dtype='object')
# 索引默认是 0, 1, 2，不是 'name'
# 重置索引
df = df.reset_index(drop=True)
# 坑点三：inplace 参数的陷阱
df.drop(columns=['score'], inplace=True)  # 很多初学者以为必须这么写
# 其实更清晰的方式是：
df = df.drop(columns=['score'])  # 链式调用更方便

2.3 内存优化

处理大数据集时，内存占用是个大问题：

# 默认 int64，占用大量内存
df = pd.DataFrame({'id': range(1000000)})
print(df['id'].memory_usage())  # 8000008 bytes
# 优化：使用更小的数据类型
df['id'] = df['id'].astype('int32')
print(df['id'].memory_usage())  # 4000004 bytes
# 对于类别数据，使用 category 类型
df['category'] = ['A', 'B', 'C'] * 333333 + ['A']
df['category'] = df['category'].astype('category')
# 内存减少 90%+

三、机器学习：Scikit-learn 的正确打开方式

3.1 数据泄露：最隐蔽的 bug

数据泄露（Data Leakage）是指在训练时用了不该用的信息，导致评估结果虚高。

from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
# 错误示范：在划分前做归一化
scaler = StandardScaler()
X_scaled = scaler.fit_transform(X)  # 用了全局统计量
X_train, X_test, y_train, y_test = train_test_split(X_scaled, y)
# 测试集的信息泄露到了训练中
# 正确做法：在划分后，只用训练集拟合
X_train, X_test, y_train, y_test = train_test_split(X, y)
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)  # 只用训练集
X_test_scaled = scaler.transform(X_test)  # 测试集只用 transform

3.2 Pipeline：避免数据泄露的最佳实践

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.decomposition import PCA
from sklearn.ensemble import RandomForestClassifier
# 创建 Pipeline
pipe = Pipeline([
    ('scaler', StandardScaler()),
    ('pca', PCA(n_components=10)),
    ('clf', RandomForestClassifier())
])
# 训练（自动避免数据泄露）
pipe.fit(X_train, y_train)
# 预测
y_pred = pipe.predict(X_test)
# 交叉验证
from sklearn.model_selection import cross_val_score
scores = cross_val_score(pipe, X, y, cv=5)

3.3 模型保存与加载

import joblib
# 保存
joblib.dump(pipe, 'model_pipeline.pkl')
# 加载
loaded_pipe = joblib.load('model_pipeline.pkl')
# 注意：加载时需要相同的 sklearn 版本，否则可能报错
# 解决方案：在 requirements.txt 中锁定版本
# scikit-learn==1.3.0

四、深度学习：PyTorch vs TensorFlow

4.1 框架选择

2024 年的格局：

• PyTorch：学术界主流，动态图，调试友好，生态活跃
• TensorFlow/Keras：工业界主流，部署方便，但 PyTorch 正在追赶
• JAX：新兴力量，高性能，但学习曲线陡峭

4.2 PyTorch 常见坑点

坑点一：维度顺序

import torch
import torch.nn as nn
# CNN 输入：(batch, channels, height, width)
# 这是 PyTorch 的默认格式（NCHW）
# 但有些数据集是 NHWC 格式
# 错误
x = torch.randn(32, 224, 224, 3)  # NHWC
conv = nn.Conv2d(3, 64, kernel_size=3)
output = conv(x)  # 报错！
# 正确
x = x.permute(0, 3, 1, 2)  # NHWC -> NCHW
output = conv(x)  # OK

坑点二：设备管理

device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = MyModel().to(device)
data = data.to(device)
target = target.to(device)
# 忘记 .to(device) 是最常见的错误
# 报错：Expected all tensors to be on the same device

坑点三：梯度计算

model.train()  # 训练模式
optimizer.zero_grad()  # 清零梯度（必须！）
output = model(data)
loss = criterion(output, target)
loss.backward()  # 计算梯度
optimizer.step()  # 更新参数
# 评估时
model.eval()  # 评估模式
with torch.no_grad():  # 不计算梯度，节省内存
    output = model(test_data)

4.3 训练循环的标准写法

def train_epoch(model, dataloader, optimizer, criterion, device):
    model.train()
    total_loss = 0
    
    for batch_idx, (data, target) in enumerate(dataloader):
        data, target = data.to(device), target.to(device)
        
        optimizer.zero_grad()
        output = model(data)
        loss = criterion(output, target)
        loss.backward()
        optimizer.step()
        
        total_loss += loss.item()
        
        if batch_idx % 100 == 0:
            print(f'Batch {batch_idx}, Loss: {loss.item():.4f}')
    
    return total_loss / len(dataloader)
def evaluate(model, dataloader, criterion, device):
    model.eval()
    total_loss = 0
    correct = 0
    
    with torch.no_grad():
        for data, target in dataloader:
            data, target = data.to(device), target.to(device)
            output = model(data)
            loss = criterion(output, target)
            total_loss += loss.item()
            pred = output.argmax(dim=1)
            correct += (pred == target).sum().item()
    
    accuracy = correct / len(dataloader.dataset)
    return total_loss / len(dataloader), accuracy
# 主训练循环
for epoch in range(num_epochs):
    train_loss = train_epoch(model, train_loader, optimizer, criterion, device)
    val_loss, val_acc = evaluate(model, val_loader, criterion, device)
    
    print(f'Epoch {epoch}: Train Loss={train_loss:.4f}, Val Loss={val_loss:.4f}, Val Acc={val_acc:.4f}')

五、大模型开发：HuggingFace 生态

5.1 Transformers 库基础

from transformers import AutoTokenizer, AutoModel
# 加载预训练模型
model_name = "bert-base-chinese"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)
# 文本编码
text = "这是一个测试句子"
inputs = tokenizer(text, return_tensors="pt")
outputs = model(**inputs)
# 获取句子向量
sentence_embedding = outputs.last_hidden_state[:, 0, :]  # [CLS] token

5.2 模型下载与缓存

# 默认缓存位置：~/.cache/huggingface/
# 国内下载慢？使用镜像
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
# 或者手动下载后指定本地路径
model = AutoModel.from_pretrained("./local-model-path")

5.3 Prompt Engineering 基础

from openai import OpenAI
client = OpenAI(api_key="your_key")
# 糟糕的 prompt
prompt = "写一篇文章"
# 好的 prompt
prompt = """
你是一位资深的技术博客作者，擅长将复杂概念用简单的语言解释清楚。
请写一篇关于"AI Agent 架构设计"的技术文章，要求：
1. 字数 1000-1500 字
2. 包含至少 2 个代码示例
3. 使用 markdown 格式
4. 面向有一定编程基础的开发者
文章结构建议：
引言：什么是 AI Agent
核心组件：记忆、工具、规划
实战案例
总结
"""
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": prompt}]
)
print(response.choices[0].message.content)

六、代码质量：让代码更专业

6.1 类型注解

Python 3.5+ 支持类型注解，让代码更清晰：

from typing import List, Dict, Optional, Union
def process_data(
    data: List[Dict[str, Union[str, int]]],
    threshold: int = 50
) -> Dict[str, float]:
    """
    处理数据并返回统计结果
    
    Args:
        data: 输入数据列表
        threshold: 过滤阈值
    
    Returns:
        统计结果字典
    """
    filtered = [item for item in data if item.get('score', 0) > threshold]
    avg_score = sum(item['score'] for item in filtered) / len(filtered) if filtered else 0
    
    return {
        'count': len(filtered),
        'average': avg_score
    }

6.2 代码格式化工具

# 安装
pip install black isort flake8 mypy
# 格式化代码
black my_script.py
isort my_script.py  # 整理 import
# 检查代码质量
flake8 my_script.py
# 类型检查
mypy my_script.py

6.3 测试驱动开发

# my_module.py
def calculate_average(numbers: list[float]) -> float:
    if not numbers:
        raise ValueError("列表不能为空")
    return sum(numbers) / len(numbers)
# test_my_module.py
import pytest
from my_module import calculate_average
def test_calculate_average_normal():
    assert calculate_average([1, 2, 3, 4, 5]) == 3.0
def test_calculate_average_empty():
    with pytest.raises(ValueError):
        calculate_average([])
def test_calculate_average_single():
    assert calculate_average([5]) == 5.0
# 运行测试
# pytest test_my_module.py -v

七、常见错误与调试技巧

7.1 常见错误类型

1. 维度错误

# 错误
import torch
a = torch.randn(3, 4)
b = torch.randn(4, 5)
c = a @ b  # OK, shape (3, 5)
# 但如果你这样做
d = torch.randn(3, 5)
e = a @ d  # RuntimeError: mat1 and mat2 shapes cannot be multiplied
# 调试技巧
print(f"a.shape: {a.shape}, d.shape: {d.shape}")

2. 索引错误

import pandas as pd
df = pd.DataFrame({'A': [1, 2, 3]})
# 错误
df.loc[5]  # KeyError: 5
# 安全访问
df.reindex([0, 1, 2, 5], fill_value=0)  # 不存在则填充默认值

3. 内存溢出

# 加载大模型时
model = AutoModel.from_pretrained("large-model")
# 如果内存不够
# 方案 1：使用低精度
model = AutoModel.from_pretrained("large-model", torch_dtype=torch.float16)
# 方案 2：设备映射（多卡）
model = AutoModel.from_pretrained("large-model", device_map="auto")
# 方案 3：梯度检查点（牺牲速度换内存）
model.gradient_checkpointing_enable()

7.2 调试工具

# 1. 使用 pdb 调试器
import pdb
def buggy_function(x):
    y = x * 2
    pdb.set_trace()  # 在这里暂停
    z = y / 0  # 这里有 bug
    return z
# 2. 使用 logging 而非 print
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
def process_data(data):
    logger.info(f"Processing {len(data)} items")
    # ...
    logger.debug("Detailed debug info")
# 3. 使用 tqdm 显示进度
from tqdm import tqdm
for i in tqdm(range(10000)):
    # 耗时操作
    pass

八、项目组织与最佳实践

8.1 推荐的项目结构

my-ai-project/
├── data/
│   ├── raw/           # 原始数据
│   ├── processed/     # 处理后的数据
│   └── external/      # 外部数据
├── src/
│   ├── __init__.py
│   ├── data/          # 数据处理模块
│   ├── models/        # 模型定义
│   └── utils/         # 工具函数
├── notebooks/         # Jupyter notebooks
├── tests/             # 测试文件
├── requirements.txt   # 依赖清单
├── setup.py           # 安装脚本
└── README.md          # 项目说明

8.2 配置管理

# 使用 dataclass 管理配置
from dataclasses import dataclass
@dataclass
class TrainingConfig:
    batch_size: int = 32
    learning_rate: float = 1e-4
    num_epochs: int = 10
    device: str = "cuda"
    
    def __post_init__(self):
        if self.device == "cuda" and not torch.cuda.is_available():
            print("CUDA not available, using CPU")
            self.device = "cpu"
config = TrainingConfig(batch_size=64)

8.3 实验追踪

# 使用 wandb 或 tensorboard 追踪实验
import wandb
wandb.init(project="my-project", config={
    "learning_rate": 1e-4,
    "batch_size": 32
})
# 记录指标
wandb.log({"loss": loss.item(), "accuracy": acc})
# 训练结束
wandb.finish()

九、学习资源推荐

9.1 官方文档（最重要）