1.2 安装与环境配置

学习目标

读完本节，你将能够：

• 熟练搭建LangChain开发环境
• 掌握不同操作系统的安装方法
• 配置API密钥和认证信息
• 解决常见的环境配置问题
• 优化开发环境性能

1.2.1 环境准备

💻 系统要求

推荐配置

• 操作系统: Windows 10/11, macOS 10.15+, Ubuntu 20.04+
• Python版本: 3.8, 3.9, 3.10, 3.11
• 内存: 8GB+ (推荐16GB)
• 存储: 10GB+ 可用空间
• 网络: 稳定的互联网连接

最低配置

• 操作系统: Windows 8, macOS 10.13, Ubuntu 18.04
• Python版本: 3.7+
• 内存: 4GB
• 存储: 5GB 可用空间

🔧 开发工具推荐

必备工具

# Python 3.8+ 
python --version  # 应显示 3.8.x 或更高版本

# pip (Python包管理器)
pip --version

# Git (版本控制)
git --version

# 虚拟环境
# Python内置venv模块
python -m venv --version
​

可选工具

# VS Code (推荐)
code --version

# PyCharm Professional
# 或其他IDE如Jupyter Notebook, Sublime Text
​

1.2.2 Python环境搭建

📦 方案一：venvenv虚拟环境

创建虚拟环境

# 创建项目目录
mkdir langchain-project
cd langchain-project

# 创建虚拟环境
python -m venv langchain-env

# 激活虚拟环境
# Windows
.\langchain-env\Scripts\activate

# macOS/Linux
source langchain-env/bin/activate

# 验证激活状态
which python  # 应显示虚拟环境中的Python路径
​

升级pip

# 升级到最新版本
pip install --upgrade pip

# 验证升级
pip --version
​

📦 方案二：conda虚拟环境

# 创建conda环境
conda create -n langchain python=3.10

# 激活conda环境
conda activate langchain

# 验证环境
conda info --envs
​

📦 方案三：Docker容器化

创建Dockerfile

# Dockerfile
FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 复制requirements文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 设置工作目录
WORKDIR /app

# 启动命令
CMD ["python", "app.py"]
​

创建docker-compose.yml

version: '3.8'
services:
  langchain-app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - .:/app
      - ./data:/app/data
    restart: unless-stopped
​

1.2.3 LangChain安装

🚀 基础安装

最新版本安装

# 安装最新版本的LangChain
pip install langchain

# 验证安装
python -c "import langchain; print(f'LangChain版本: {langchain.__version__}')"
​

指定版本安装

# 安装特定版本
pip install langchain==0.1.0

# 或从源码安装
pip install git+https://github.com/langchain-ai/langchain.git
​

🔌 组件模块安装

OpenAI集成

# OpenAI模型支持
pip install langchain-openai

# 或包含在完整安装中
pip install "langchain[openai]"
​

Anthropic Claude集成

# Anthropic Claude模型支持
pip install langchain-anthropic
​

Google集成

# Google模型支持
pip install langchain-google
​

向量存储支持

# Chroma向量存储
pip install langchain chromadb

# FAISS向量存储
pip install langchain faiss-cpu

# Pinecone向量存储
pip install langchain pinecone-client
​

文档加载器

# PDF文档加载
pip install langchain pypdf

# 网页内容加载
pip install langchain beautifulsoup4

# Office文档加载
pip install langchain-docs python-docx
​

工具和代理

# 代理和工具支持
pip install langchain-experimental

# 搜索工具
pip install langchain-community google-search-results
​

1.2.4 API密钥配置

🔑 OpenAI API配置

获取API密钥

1. 访问 OpenAI Platform
2. 注册并登录账户
3. 进入API Keys页面
4. 创建新的API密钥
5. 复制密钥并保存

环境变量配置

# 临时设置（当前终端会话生效）
export OPENAI_API_KEY="your-api-key-here"

# 永久设置（推荐）
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# 或在~/.zshrc中设置（macOS Catalina+）
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
​

Python代码配置

import os
from langchain_openai import ChatOpenAI

# 方法1：环境变量
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 方法2：直接传入
llm = ChatOpenAI(
    api_key="your-api-key-here",
    model="gpt-4"
)

# 方法3：配置文件
config = {
    "openai_api_key": "your-api-key-here"
}
​

🔑 Anthropic API配置

获取API密钥

1. 访问 Anthropic Console
2. 注册并登录账户
3. 在API Keys页面创建密钥
4. 复制密钥

配置方法

# 环境变量
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Python配置
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
    api_key="your-anthropic-api-key",
    model="claude-3-sonnet"
)
​

🔑 其他API配置

Google Gemini API

export GOOGLE_API_KEY="your-google-api-key"

from langchain_google import ChatGoogle

llm = ChatGoogle(
    api_key="your-google-api-key",
    model="gemini-pro"
)
​

Azure OpenAI API

export AZURE_OPENAI_API_KEY="your-azure-key"
export AZURE_OPENAI_ENDPOINT="your-endpoint"
export AZURE_OPENAI_API_VERSION="2024-02-01"

from langchain_openai import AzureChatOpenAI

llm = AzureChatOpenAI(
    azure_deployment="your-deployment-name",
    openai_api_version="2024-02-01"
)
​

1.2.5 项目结构设计

📁 推荐项目结构

langchain-project/
├── README.md                    # 项目说明
├── requirements.txt             # Python依赖
├── environment.yml             # Conda环境文件（可选）
├── config/
│   ├── __init__.py
│   ├── settings.py             # 配置文件
│   └── api_keys.py            # API密钥管理
├── src/
│   ├── __init__.py
│   ├── main.py                # 主程序
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── helpers.py         # 辅助函数
│   │   └── logging.py        # 日志配置
│   ├── agents/
│   │   ├── __init__.py
│   │   └── ml_agent.py       # 代理实现
│   ├── chains/
│   │   ├── __init__.py
│   │   └── analysis_chain.py  # 链实现
│   ├── memory/
│   │   ├── __init__.py
│   │   └── storage.py         # 记忆存储
│   └── tools/
│       ├── __init__.py
│       └── search_tool.py    # 工具实现
├── data/
│   ├── raw/                  # 原始数据
│   ├── processed/            # 处理后的数据
│   └── vector_stores/        # 向量存储
├── tests/
│   ├── __init__.py
│   ├── test_agents.py
│   ├── test_chains.py
│   └── test_utils.py
├── notebooks/                 # Jupyter笔记本
├── docs/                     # 文档
├── scripts/                  # 辅助脚本
├── logs/                     # 日志文件
└── .gitignore                # Git忽略文件
​

⚙️ 配置文件示例

config/settings.py

import os
from pathlib import Path

class Config:
    # 项目根目录
    PROJECT_ROOT = Path(__file__).parent.parent
    
    # API配置
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
    ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
    GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
    
    # 模型配置
    DEFAULT_LLM_MODEL = "gpt-4"
    DEFAULT_TEMPERATURE = 0.7
    DEFAULT_MAX_TOKENS = 2000
    
    # 向量存储配置
    VECTOR_STORE_PATH = PROJECT_ROOT / "data" / "vector_stores"
    EMBEDDING_MODEL = "text-embedding-ada-002"
    
    # 记忆配置
    MEMORY_PATH = PROJECT_ROOT / "data" / "memory"
    
    # 日志配置
    LOG_LEVEL = "INFO"
    LOG_FILE = PROJECT_ROOT / "logs" / "app.log"
    
    # 安全配置
    MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10MB
    RATE_LIMIT = 100  # 每分钟请求数
​

config/api_keys.py

import os
from typing import Optional

class APIKeys:
    """安全地管理API密钥"""
    
    def __init__(self):
        self._openai_key: Optional[str] = None
        self._anthropic_key: Optional[str] = None
        self._google_key: Optional[str] = None
    
    @property
    def openai_key(self) -> str:
        if not self._openai_key:
            self._openai_key = os.getenv("OPENAI_API_KEY")
            if not self._openai_key:
                raise ValueError("OpenAI API key not configured")
        return self._openai_key
    
    @property
    def anthropic_key(self) -> str:
        if not self._anthropic_key:
            self._anthropic_key = os.getenv("ANTHROPIC_API_KEY")
            if not self._anthropic_key:
                raise ValueError("Anthropic API key not configured")
        return self._anthropic_key
    
    @property
    def google_key(self) -> str:
        if not self._google_key:
            self._google_key = os.getenv("GOOGLE_API_KEY")
            if not self._google_key:
                raise ValueError("Google API key not configured")
        return self._google_key

# 全局实例
api_keys = APIKeys()
​

1.2.6 开发环境测试

🔍 环境验证脚本

environment_test.py

import os
import sys
import traceback
from typing import Dict, List, Any

class EnvironmentTester:
    """开发环境测试工具"""
    
    def __init__(self):
        self.results: Dict[str, bool] = {}
        self.details: Dict[str, str] = {}
    
    def test_python_version(self) -> bool:
        """测试Python版本"""
        try:
            version = sys.version_info
            if version >= (3, 8):
                self.results["python_version"] = True
                self.details["python_version"] = f"Python {version.major}.{version.minor}.{version.micro}"
                return True
            else:
                self.results["python_version"] = False
                self.details["python_version"] = f"Python {version.major}.{version.minor}.{version.micro} - 需要Python 3.8+"
                return False
        except Exception as e:
            self.results["python_version"] = False
            self.details["python_version"] = f"错误: {str(e)}"
            return False
    
    def test_pip_version(self) -> bool:
        """测试pip版本"""
        try:
            import pip
            self.results["pip_version"] = True
            self.details["pip_version"] = f"pip {pip.__version__}"
            return True
        except Exception as e:
            self.results["pip_version"] = False
            self.details["pip_version"] = f"错误: {str(e)}"
            return False
    
    def test_langchain_installation(self) -> bool:
        """测试LangChain安装"""
        try:
            import langchain
            self.results["langchain"] = True
            self.details["langchain"] = f"LangChain {langchain.__version__}"
            return True
        except ImportError as e:
            self.results["langchain"] = False
            self.details["langchain"] = f"未安装: {str(e)}"
            return False
    
    def test_api_keys(self) -> bool:
        """测试API密钥配置"""
        api_keys = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY"]
        self.results["api_keys"] = {}
        self.details["api_keys"] = {}
        
        all_good = True
        for key in api_keys:
            try:
                value = os.getenv(key)
                if value and len(value) > 10:  # 简单验证
                    self.results["api_keys"][key] = True
                    self.details["api_keys"][key] = f"✓ {key} 已配置"
                else:
                    self.results["api_keys"][key] = False
                    self.details["api_keys"][key] = f"✗ {key} 未配置或无效"
                    all_good = False
            except Exception as e:
                self.results["api_keys"][key] = False
                self.details["api_keys"][key] = f"✗ {key} 错误: {str(e)}"
                all_good = False
        
        return all_good
    
    def test_llm_connection(self) -> bool:
        """测试LLM连接"""
        try:
            from langchain_openai import ChatOpenAI
            
            llm = ChatOpenAI(
                model="gpt-3.5-turbo",
                temperature=0,
                max_tokens=10
            )
            
            # 发送测试请求
            response = llm.invoke("Hello")
            if response.content:
                self.results["llm_connection"] = True
                self.details["llm_connection"] = "✓ LLM连接成功"
                return True
            else:
                self.results["llm_connection"] = False
                self.details["llm_connection"] = "✗ LLM响应为空"
                return False
        except Exception as e:
            self.results["llm_connection"] = False
            self.details["llm_connection"] = f"✗ LLM连接失败: {str(e)}"
            return False
    
    def test_vector_store(self) -> bool:
        """测试向量存储"""
        try:
            from langchain.vectorstores import Chroma
            from langchain_openai import OpenAIEmbeddings
            
            # 创建临时向量存储
            embeddings = OpenAIEmbeddings()
            vector_store = Chroma.from_texts(
                ["测试文档"],
                embedding=embeddings,
                persist_directory="./test_chroma"
            )
            
            # 测试搜索
            results = vector_store.similarity_search("测试", k=1)
            
            # 清理
            import shutil
            shutil.rmtree("./test_chroma")
            
            self.results["vector_store"] = True
            self.details["vector_store"] = "✓ 向量存储功能正常"
            return True
        except Exception as e:
            self.results["vector_store"] = False
            self.details["vector_store"] = f"✗ 向量存储测试失败: {str(e)}"
            return False
    
    def run_all_tests(self) -> Dict[str, Any]:
        """运行所有测试"""
        print("🔍 开始环境测试...")
        print("=" * 50)
        
        tests = [
            ("Python版本", self.test_python_version),
            ("Pip版本", self.test_pip_version),
            ("LangChain安装", self.test_langchain_installation),
            ("API密钥配置", self.test_api_keys),
            ("LLM连接", self.test_llm_connection),
            ("向量存储", self.test_vector_store),
        ]
        
        for name, test_func in tests:
            print(f"📋 {name}...")
            try:
                test_func()
            except Exception as e:
                self.results[name] = False
                self.details[name] = f"✗ 测试执行失败: {str(e)}"
            
            status = "✅ 通过" if self.results.get(name, False) else "❌ 失败"
            print(f"   {status}")
        
        # 输出详细结果
        print("\n📊 详细结果:")
        print("-" * 30)
        
        all_passed = True
        for name, passed in self.results.items():
            if name == "api_keys":
                for key, status in passed.items():
                    print(f"  {self.details[key]}")
                all_passed &= all(passed.values())
            else:
                print(f"  {self.details[name]}")
                all_passed &= passed
        
        print("\n" + "=" * 50)
        if all_passed:
            print("🎉 所有测试通过！环境配置正确。")
        else:
            print("⚠️ 部分测试失败，请检查配置。")
        
        return {
            "all_passed": all_passed,
            "results": self.results,
            "details": self.details
        }

if __name__ == "__main__":
    tester = EnvironmentTester()
    results = tester.run_all_tests()
​

🚀 运行测试

# 确保在虚拟环境中运行
source langchain-env/bin/activate  # 或 conda activate langchain

# 运行环境测试
python environment_test.py
​

1.2.7 常见问题与解决方案

🚫 问题1：ModuleNotFoundError

症状

ModuleNotFoundError: No module named 'langchain'
​

解决方案

# 1. 检查虚拟环境
which python  # 确认在虚拟环境中

# 2. 重新安装
pip install --upgrade pip
pip install langchain

# 3. 检查Python路径
python -c "import sys; print(sys.path)"
​

🚫 问题2：API密钥未配置

症状

Error: OPENAI_API_KEY not configured
​

解决方案

# 1. 检查环境变量
echo $OPENAI_API_KEY

# 2. 设置环境变量
export OPENAI_API_KEY="your-key-here"

# 3. 验证设置
python -c "import os; print(os.getenv('OPENAI_API_KEY'))"
​

🚫 问题3：网络连接问题

症状

ConnectionError: Failed to establish connection
​

解决方案

# 1. 测试网络连接
ping api.openai.com

# 2. 使用代理
export HTTP_PROXY="http://proxy:port"
export HTTPS_PROXY="https://proxy:port"

# 3. 设置超时
import os
os.environ["REQUESTS_TIMEOUT"] = "30"
​

🚫 问题4：内存不足

症状

MemoryError: Unable to allocate array
​

解决方案

# 1. 减少批量大小
batch_size = 32  # 从64减少到32

# 2. 使用生成器
def data_generator():
    for item in large_dataset:
        yield item

# 3. 优化内存使用
import gc
gc.collect()
​

🚫 问题5：版本冲突

症状

ImportError: cannot import name 'ChatOpenAI' from 'langchain'
​

解决方案

# 1. 检查版本
pip show langchain

# 2. 升级到最新版本
pip install --upgrade langchain

# 3. 安装特定版本
pip install langchain==0.1.0
​

1.2.8 性能优化配置

⚡ 优化1：缓存配置

# 启用缓存
from langchain.cache import SQLiteCache
from langchain.globals import set_llm_cache

# 设置缓存路径
cache_path = "./cache/langchain_cache.db"
set_llm_cache(SQLiteCache(database_path=cache_path))

# 自动缓存装饰器
from functools import lru_cache

@lru_cache(maxsize=128)
def cached_llm_call(prompt: str):
    return llm.invoke(prompt)
​

⚡ 优化2：异步调用

import asyncio
from langchain_core.runnables import RunnableLambda

async def async_llm_call(prompt: str):
    llm = ChatOpenAI()
    response = await llm.ainvoke(prompt)
    return response.content

# 批量异步调用
async def batch_async_call(prompts: List[str]):
    tasks = [async_llm_call(prompt) for prompt in prompts]
    return await asyncio.gather(*tasks)
​

⚡ 优化3：内存管理

# 内存监控
import psutil
import threading

class MemoryMonitor:
    def __init__(self, threshold_mb=500):
        self.threshold_mb = threshold_mb
        self.running = False
    
    def start_monitoring(self):
        self.running = True
        monitor_thread = threading.Thread(target=self._monitor)
        monitor_thread.daemon = True
        monitor_thread.start()
    
    def _monitor(self):
        while self.running:
            memory_mb = psutil.Process().memory_info().rss / 1024 / 1024
            if memory_mb > self.threshold_mb:
                print(f"⚠️ 内存使用超过阈值: {memory_mb:.1f}MB")
            time.sleep(5)

# 使用监控器
monitor = MemoryMonitor(threshold_mb=1000)
monitor.start_monitoring()
​

1.2.9 部署配置

🐳 Docker部署

创建requirements.txt

langchain>=0.1.0
langchain-openai>=0.0.2
python-dotenv>=1.0.0
fastapi>=0.104.0
uvicorn>=0.24.0
​

创建deploy.sh

#!/bin/bash
# 部署脚本

# 设置环境变量
export OPENAI_API_KEY="${OPENAI_API_KEY}"
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}"

# 构建镜像
docker build -t langchain-app .

# 运行容器
docker run -d \
  --name langchain-service \
  -p 8000:8000 \
  -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  langchain-app
​

☁️ 云平台部署

AWS Lambda部署

# lambda_function.py
import json
import os
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate

def lambda_handler(event, context):
    # 初始化LLM
    llm = ChatOpenAI(
        model="gpt-4",
        temperature=0.3
    )
    
    # 处理请求
    prompt = event.get('prompt', '')
    response = llm.invoke(prompt)
    
    return {
        'statusCode': 200,
        'body': json.dumps({
            'response': response.content,
            'tokens_used': len(response.content.split())
        })
    }
​

1.2.10 总结与最佳实践

✅ 成功检查清单

• Python 3.8+ 已安装
• 虚拟环境已创建和激活
• LangChain及相关依赖已安装
• API密钥已正确配置
• 环境测试脚本全部通过
• 项目结构清晰完整
• 性能优化已配置

📝 最佳实践

1. 环境隔离

• 始终使用虚拟环境
• 不同项目使用不同的环境
• 定期清理不用的依赖

2. 安全管理

• 不要在代码中硬编码API密钥
• 使用环境变量或配置管理工具
• 定期轮换API密钥

3. 性能监控

• 实施API调用监控
• 设置合理的超时和重试机制
• 定期检查内存使用情况

4. 版本控制

• 固定依赖版本
• 使用requirements.txt或environment.yml
• 定期更新安全补丁

🔗 下节预告

下一节我们将学习1.3 基础组件概览，包括：

• 核心组件详细介绍
• 组件间的协作关系
• 组件选择指南
• 实际应用案例

准备好了吗？让我们继续探索LangChain的组件世界！🚀