1.2 技术栈准备与环境搭建

导读：本节将详细介绍大模型应用开发所需的技术栈和环境搭建过程，为你构建完整的开发环境奠定基础。

1.2.1 Python环境配置

Python版本选择

大模型应用开发建议使用Python 3.8-3.12版本，其中Python 3.9-3.11是最推荐的选择：

# 检查Python版本
python --version  # 或 python3 --version

# 推荐版本配置
# Python 3.9+ 支持更好的异步编程和类型注解
# Python 3.11+ 提供更好的性能和内存管理
​

虚拟环境管理

创建虚拟环境：

# 使用venv创建虚拟环境
python -m venv llm-dev-env

# 激活虚拟环境
# Linux/Mac
source llm-dev-env/bin/activate
# Windows
llm-dev-env\Scripts\activate

# 验证激活
which python  # Linux/Mac
where python  # Windows
​

使用conda管理环境（推荐用于数据科学项目）：

# 创建新环境
conda create -n llm-dev python=3.11

# 激活环境
conda activate llm-dev

# 安装必要的包
conda install -c conda-forge openpyxl pandas numpy
​

核心依赖包安装

基础依赖包：

# 基础HTTP请求库
pip install requests httpx

# 异步HTTP客户端
pip install aiohttp asyncio

# 数据处理
pip install pandas numpy openpyxl

# JSON处理
pip install pydantic

# 日志管理
pip install loguru

# 配置管理
pip install python-dotenv
​

大模型相关包：

# OpenAI客户端
pip install openai

# Anthropic Claude客户端
pip install anthropic

# Hugging Face Transformers
pip install transformers torch

# 向量数据库
pip install faiss-cpu  # CPU版本
# 或
pip install faiss-gpu  # GPU版本

# LangChain框架
pip install langchain langchain-openai

# LlamaIndex
pip install llama-index
​

开发工具包：

# 代码质量工具
pip install black isort flake8 mypy

# 测试工具
pip install pytest pytest-asyncio

# 类型检查
pip install types-requests types-python-dateutil
​

requirements.txt 文件管理

创建requirements.txt文件管理依赖：

# requirements.txt
# 基础依赖
requests>=2.31.0
httpx>=0.24.0
pandas>=2.0.0
numpy>=1.24.0
python-dotenv>=1.0.0

# 大模型相关
openai>=1.3.0
anthropic>=0.3.0
transformers>=4.30.0
langchain>=0.1.0
llama-index>=0.9.0

# 向量数据库
faiss-cpu>=1.7.4

# 开发工具
black>=23.0.0
isort>=5.12.0
flake8>=6.0.0
pytest>=7.4.0

# 数据处理
pydantic>=2.0.0
loguru>=0.7.0
​

安装依赖：

pip install -r requirements.txt
​

1.2.2 开发环境配置

环境变量配置

创建.env文件管理环境变量：

# .env文件
# OpenAI配置
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic配置
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 模型配置
DEFAULT_MODEL=gpt-4-turbo-preview
MAX_TOKENS=4000
TEMPERATURE=0.7

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

# 数据库配置
DATABASE_URL=sqlite:///./data/app.db
VECTOR_DB_PATH=./vectors/

# API配置
API_RATE_LIMIT=100
API_TIMEOUT=30
​

环境变量加载：

# config.py
import os
from dotenv import load_dotenv
from pydantic import BaseSettings

class Settings(BaseSettings):
    # API配置
    openai_api_key: str = os.getenv("OPENAI_API_KEY", "")
    anthropic_api_key: str = os.getenv("ANTHROPIC_API_KEY", "")
    default_model: str = os.getenv("DEFAULT_MODEL", "gpt-4-turpo-preview")
    max_tokens: int = int(os.getenv("MAX_TOKENS", "4000"))
    temperature: float = float(os.getenv("TEMPERATURE", "0.7"))
    
    # 日志配置
    log_level: str = os.getenv("LOG_LEVEL", "INFO")
    log_file: str = os.getenv("LOG_FILE", "logs/app.log")
    
    # 数据库配置
    database_url: str = os.getenv("DATABASE_URL", "sqlite:///./data/app.db")
    vector_db_path: str = os.getenv("VECTOR_DB_PATH", "./vectors/")
    
    # API配置
    api_rate_limit: int = int(os.getenv("API_RATE_LIMIT", "100"))
    api_timeout: int = int(os.getenv("API_TIMEOUT", "30"))
    
    class Config:
        env_file = ".env"

# 加载环境变量
load_dotenv()

# 创建设置实例
settings = Settings()
​

项目结构规范

推荐的项目结构：

llm-app-project/
├── README.md
├── requirements.txt
├── .env
├── .gitignore
├── config.py
├── main.py
├── app/
│   ├── __init__.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── llm_client.py
│   │   ├── vector_store.py
│   │   └── prompts.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── chat_service.py
│   │   ├── vector_service.py
│   │   └── api_service.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── logger.py
│   │   ├── helpers.py
│   │   └── exceptions.py
│   └── api/
│       ├── __init__.py
│       ├── routes/
│       │   ├── __init__.py
│       │   ├── chat.py
│       │   └── health.py
│       └── middleware/
│           ├── __init__.py
│           └── error_handler.py
├── tests/
│   ├── __init__.py
│   ├── test_models/
│   ├── test_services/
│   └── test_api/
├── data/
│   ├── prompts/
│   └── knowledge_base/
├── vectors/
├── logs/
└── docs/
    ├── api.md
    ├── deployment.md
    └── troubleshooting.md
​

目录创建脚本

创建项目的初始结构：

#!/bin/bash
# create_project.sh

PROJECT_NAME=${1:-llm-app-project}

# 创建主要目录
mkdir -p $PROJECT_NAME
cd $PROJECT_NAME

# 创建应用目录结构
mkdir -p app/{models,services,utils,api/{routes,middleware}}
mkdir -p tests/{test_models,test_services,test_api}
mkdir -p data/{prompts,knowledge_base}
mkdir -p vectors
mkdir -p logs
mkdir -p docs

# 创建Python包文件
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name "*.egg-info" -exec rm -rf {} +

# 创建__init__.py文件
find app tests -type d -exec touch {}/__init__.py \;

# 创建基础文件
touch requirements.txt .env .gitignore README.md config.py main.py

echo "项目结构创建完成: $PROJECT_NAME"
​

.gitignore 文件配置

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# 虚拟环境
venv/
env/
ENV/
env.bak/
venv.bak/

# 环境变量
.env
.env.local
.env.*.local

# 数据文件
*.db
*.sqlite
*.sqlite3
data/
vectors/
logs/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# 临时文件
tmp/
temp/
*.tmp
*.temp

# 备份文件
*.bak
*.backup
​

1.2.3 开发工具链

代码编辑器配置

VS Code 配置：

创建.vscode/settings.json：

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  },
  "files.associations": {
    "*.env": "ini"
  },
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.analysis.typeCheckingMode": "basic"
}
​

安装推荐的VS Code扩展：

# 推荐的VS Code扩展
code --install-extension ms-python.python
code --install-extension ms-toolsai.jupyter
code --install-extension ms-toolsai.vscode-jupyter-cell-tags
code --install-extension ms-toolsai.vscode-jupyter-keyshortcuts
code --install-extension ms-toolsai.vscode-jupyter-powertoys
code --install-extension ms-toolsai.vscode-ai
code --install-extension ms-toolsai.vscode-lm
​

调试工具配置

Python调试器配置：

创建.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "Python: Debug LLM Client",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": [
        "tests/test_models/test_llm_client.py",
        "-v",
        "-s"
      ],
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      "name": "Python: Attach",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "."
        }
      ],
      "justMyCode": true
    }
  ]
}
​

日志配置：

# utils/logger.py
import logging
import sys
from pathlib import Path
from loguru import logger
from config import settings

# 确保日志目录存在
log_dir = Path(settings.log_file).parent
log_dir.mkdir(exist_ok=True)

# 配置loguru
logger.remove()  # 移除默认处理器

# 添加控制台输出
logger.add(
    sys.stdout,
    level=settings.log_level,
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
    colorize=True
)

# 添加文件输出
logger.add(
    settings.log_file,
    level=settings.log_level,
    format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
    rotation="1 day",
    retention="30 days",
    compression="zip"
)

def get_logger(name: str):
    """获取指定名称的日志器"""
    return logger.bind(name=name)
​

性能监控工具

性能监控配置：

# utils/monitoring.py
import time
import psutil
import threading
from functools import wraps
from typing import Callable, Any
from config import settings
from utils.logger import get_logger

logger = get_logger(__name__)

class PerformanceMonitor:
    """性能监控类"""
    
    def __init__(self):
        self.start_time = None
        self.memory_usage = []
        self.cpu_usage = []
        
    def start(self):
        """开始监控"""
        self.start_time = time.time()
        self.memory_usage = []
        self.cpu_usage = []
        
        # 启动监控线程
        self.monitor_thread = threading.Thread(target=self._monitor_resources)
        self.monitor_thread.daemon = True
        self.monitor_thread.start()
        
    def stop(self):
        """停止监控"""
        if self.start_time:
            duration = time.time() - self.start_time
            avg_memory = sum(self.memory_usage) / len(self.memory_usage) if self.memory_usage else 0
            avg_cpu = sum(self.cpu_usage) / len(self.cpu_usage) if self.cpu_usage else 0
            
            logger.info(f"性能监控 - 持续时间: {duration:.2f}s, 平均内存: {avg_memory:.2f}MB, 平均CPU: {avg_cpu:.1f}%")
            
    def _monitor_resources(self):
        """监控系统资源使用情况"""
        while True:
            try:
                process = psutil.Process()
                memory_info = process.memory_info()
                cpu_percent = process.cpu_percent()
                
                self.memory_usage.append(memory_info.rss / 1024 / 1024)  # 转换为MB
                self.cpu_usage.append(cpu_percent)
                
                time.sleep(1)
            except Exception as e:
                logger.error(f"资源监控错误: {e}")
                break

def monitor_performance(func: Callable) -> Callable:
    """性能监控装饰器"""
    @wraps(func)
    def wrapper(*args, **kwargs) -> Any:
        monitor = PerformanceMonitor()
        monitor.start()
        
        try:
            result = func(*args, **kwargs)
            return result
        finally:
            monitor.stop()
            
    return wrapper

def track_api_calls(func: Callable) -> Callable:
    """API调用监控装饰器"""
    @wraps(func)
    def wrapper(*args, **kwargs) -> Any:
        start_time = time.time()
        
        try:
            result = func(*args, **kwargs)
            duration = time.time() - start_time
            
            logger.info(f"API调用监控 - {func.__name__}: {duration:.3f}s")
            return result
        except Exception as e:
            duration = time.time() - start_time
            logger.error(f"API调用监控 - {func.__name__} 失败: {duration:.3f}s, 错误: {e}")
            raise
            
    return wrapper
​

1.2.4 环境验证测试

环境验证脚本

创建environment_check.py脚本验证环境配置：

# environment_check.py
import sys
import importlib
from pathlib import Path

def check_python_version():
    """检查Python版本"""
    version = sys.version_info
    if version.major == 3 and version.minor >= 8:
        print(f"✓ Python版本检查通过: {version.major}.{version.minor}.{version.micro}")
        return True
    else:
        print(f"✗ Python版本不符合要求: {version.major}.{version.minor}.{version.micro}")
        print("要求: Python 3.8+")
        return False

def check_package(package_name: str, import_name: str = None):
    """检查包是否安装"""
    try:
        import_name = import_name or package_name
        module = importlib.import_module(import_name)
        version = getattr(module, '__version__', '未知版本')
        print(f"✓ {package_name} 检查通过: {version}")
        return True
    except ImportError:
        print(f"✗ {package_name} 未安装")
        return False

def check_environment():
    """检查整个环境"""
    print("=" * 50)
    print("开发环境检查")
    print("=" * 50)
    
    checks = []
    
    # 检查Python版本
    checks.append(check_python_version())
    
    # 检查基础包
    base_packages = [
        ('requests', 'requests'),
        ('httpx', 'httpx'),
        ('pandas', 'pandas'),
        ('numpy', 'numpy'),
        ('python-dotenv', 'dotenv'),
    ]
    
    for package, import_name in base_packages:
        checks.append(check_package(package, import_name))
    
    # 检查大模型相关包
    llm_packages = [
        ('openai', 'openai'),
        ('anthropic', 'anthropic'),
        ('transformers', 'transformers'),
        ('langchain', 'langchain'),
        ('faiss', 'faiss'),
    ]
    
    for package, import_name in llm_packages:
        checks.append(check_package(package, import_name))
    
    # 检查开发工具
    dev_packages = [
        ('black', 'black'),
        ('isort', 'isort'),
        ('flake8', 'flake8'),
        ('pytest', 'pytest'),
    ]
    
    for package, import_name in dev_packages:
        checks.append(check_package(package, import_name))
    
    # 检查目录结构
    required_dirs = ['data', 'vectors', 'logs', 'app']
    for dir_name in required_dirs:
        if Path(dir_name).exists():
            print(f"✓ 目录 {dir_name} 存在")
            checks.append(True)
        else:
            print(f"✗ 目录 {dir_name} 不存在")
            checks.append(False)
    
    # 检查配置文件
    config_files = ['.env', 'requirements.txt']
    for file_name in config_files:
        if Path(file_name).exists():
            print(f"✓ 配置文件 {file_name} 存在")
            checks.append(True)
        else:
            print(f"✗ 配置文件 {file_name} 不存在")
            checks.append(False)
    
    print("=" * 50)
    passed = sum(checks)
    total = len(checks)
    print(f"检查结果: {passed}/{total} 项通过")
    
    if passed == total:
        print("✓ 环境检查全部通过，可以开始开发！")
        return True
    else:
        print("✗ 环境检查未通过，请根据上述提示进行配置")
        return False

if __name__ == "__main__":
    success = check_environment()
    sys.exit(0 if success else 1)
​

运行环境检查

# 运行环境检查
python environment_check.py

# 输出示例：
# ==================================================
# 开发环境检查
# ==================================================
# ✓ Python版本检查通过: 3.11.5
# ✓ requests 检查通过: 2.31.0
# ✓ httpx 检查通过: 0.24.0
# ✓ pandas 检查通过: 2.1.0
# ✓ numpy 检查通过: 1.24.3
# ✓ python-dotenv 检查通过: 1.0.0
# ✓ openai 检查通过: 1.3.0
# ✓ anthropic 检查通过: 0.3.0
# ✓ transformers 检查通过: 4.30.0
# ✓ langchain 检查通过: 0.1.0
# ✓ faiss 检查通过: 1.7.4
# ✓ black 检查通过: 23.7.0
# ✓ isort 检查通过: 5.12.0
# ✓ flake8 检查通过: 6.0.0
# ✓ pytest 检查通过: 7.4.0
# ✓ 目录 data 存在
# ✓ 目录 vectors 存在
# ✓ 目录 logs 存在
# ✓ 目录 app 存在
# ✓ 配置文件 .env 存在
# ✓ 配置文件 requirements.txt 存在
# ==================================================
# 检查结果: 19/19 项通过
# ✓ 环境检查全部通过，可以开始开发！
​

1.2.5 常见问题与解决方案

环境配置问题

问题1：Python版本不兼容

# 解决方案：使用版本管理工具
# 使用pyenv管理Python版本
pyenv install 3.11.5
pyenv local 3.11.5

# 或使用conda
conda create -n llm-dev python=3.11
conda activate llm-dev
​

问题2：依赖包安装失败

# 解决方案1：更新pip
python -m pip install --upgrade pip

# 解决方案2：使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 解决方案3：使用虚拟环境
python -m venv llm-dev-env
source llm-dev-env/bin/activate
pip install -r requirements.txt
​

问题3：OpenAI API连接失败

# 解决方案：检查网络和API密钥
# 1. 检查网络连接
curl -I https://api.openai.com

# 2. 验证API密钥
echo $OPENAI_API_KEY

# 3. 使用代理配置（如需要）
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
​

性能优化问题

问题1：内存使用过高

# 解决方案：使用生成器和分块处理
def process_large_file(file_path: str, chunk_size: int = 1024):
    """分块处理大文件"""
    with open(file_path, 'r', encoding='utf-8') as f:
        while True:
            chunk = f.read(chunk_size)
            if not chunk:
                break
            yield process_chunk(chunk)

def process_chunk(chunk: str):
    """处理单个数据块"""
    # 处理逻辑
    return result
​

问题2：API调用慢

# 解决方案：使用异步请求和缓存
import aiohttp
import asyncio
from functools import lru_cache

@lru_cache(maxsize=1000)
def get_cached_response(prompt: str):
    """缓存API响应"""
    # 调用API的逻辑
    return response

async def batch_api_requests(prompts: list):
    """批量异步API请求"""
    async with aiohttp.ClientSession() as session:
        tasks = [make_api_request(session, prompt) for prompt in prompts]
        return await asyncio.gather(*tasks)
​

调试技巧

问题1：调试LLM应用

# 解决方案：启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 或在代码中添加调试信息
def debug_llm_call(prompt: str, response: str):
    print(f"=== LLM Debug ===")
    print(f"Prompt: {prompt[:200]}...")
    print(f"Response: {response[:200]}...")
    print(f"=== End Debug ===")
​

问题2：处理异步代码调试

# 解决方案：使用异步调试器
# 安装
pip install pytest-asyncio

# 使用
async def test_async_function():
    # 测试代码
    pass

# 运行测试
pytest -s -v test_file.py
​

本章小结

通过本节的学习，你将：

✅ 掌握Python环境配置和虚拟环境管理
✅ 学会项目结构和依赖管理
✅ 熟悉开发工具链配置
✅ 掌握环境验证和性能监控
✅ 能够解决常见的环境配置问题

这些技能将为你后续的大模型应用开发提供坚实的基础。在接下来的章节中，我们将深入探讨开发工具和调试方法。

[FAQ] 常见问题

Q: 如何选择合适的Python版本？
A: 建议使用Python 3.9-3.11版本。Python 3.9+提供了更好的异步编程支持，Python 3.11+有更好的性能和内存管理。

Q: 什么时候使用venv，什么时候使用conda？
A: venv适合纯Python项目，轻量级。conda适合数据科学项目，可以管理Python版本和科学计算包。推荐优先使用venv，除非需要特定的科学计算环境。

Q: 如何处理依赖冲突？
A: 使用虚拟环境隔离不同项目的依赖。对于复杂项目，可以考虑使用Poetry或pipenv进行依赖管理。

Q: 如何优化大模型应用的性能？
A: 使用异步请求、缓存机制、批量处理、连接池等技术。对于内存密集型任务，考虑使用生成器和分块处理。

Q: 如何调试异步代码？
A: 使用异步调试器、详细的日志记录、性能监控工具。pytest-asyncio提供了很好的异步测试支持。

Q: 环境变量配置的最佳实践是什么？
A: 使用.env文件管理敏感信息，将.env添加到.gitignore。生产环境中使用环境变量管理服务，不要将密钥硬编码在代码中。