推荐语

本地化部署LangSmith+LangGraph，解决企业数据合规与开发连续性难题，这份全流程指南助你轻松实现离线调试。

核心内容：
1. 企业为何需要本地化部署LLM开发环境：数据合规与开发连续性的双重需求
2. 三种部署模式技术选型对比：从独立服务器到Kubernetes集群的适用场景分析
3. 实战四阶段部署指南：从环境准备到完整部署的详细操作步骤

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

LangSmith+LangGraph本地化部署与离线调试全流程

问题引入：为什么企业需要本地化部署LLM开发环境？

2025年3月，某金融科技公司因使用云端LangSmith服务处理客户敏感数据，违反《数据安全法》第21条"关键信息基础设施运营者在中华人民共和国境内运营中收集和产生的个人信息和重要数据应当在境内存储"的规定，被监管部门处以200万元罚款。该案例揭示了LLM开发工具云端部署在金融、医疗等敏感行业的合规风险。

无独有偶，另一AI创业公司在使用云端服务时遭遇API调用失败，导致整个开发团队停滞3小时。这两个真实事件凸显了本地化部署的迫切性——数据主权与开发连续性已成为企业LLM工程化的核心诉求。

方案解析：三种部署模式的技术选型对比

LangChain生态提供了三种本地化部署方案，我们需要根据团队规模和业务需求选择合适的路径：

选型建议：开发测试环境优先选择独立服务器模式，生产环境推荐Kubernetes部署。本文将重点讲解最具普适性的"独立服务器+LangSmith监控"组合方案，兼顾开发效率与可观测性。

实战操作：四阶段部署实施指南

第一阶段：环境准备与依赖安装

硬件要求：

• • CPU：至少4核（推荐8核）- 内存：16GB RAM（LangSmith+PostgreSQL+Redis同时运行时内存消耗约12GB）- 存储：100GB SSD（ClickHouse数据存储需要预留空间）
  软件环境：
• • 操作系统：Ubuntu 22.04 LTS / CentOS 9 / Windows 11 WSL2- Docker：24.0.0+（容器化部署核心依赖）- Python：3.12（LangGraph 1.0最低支持版本）- Git：2.30+（版本控制工具）
  基础依赖安装命令：

1
2
3
4
5
6
7
8
9
10
11

# Ubuntu系统依赖安装
sudo apt update && sudo apt install -y python3.12 python3.12-venv docker.io docker-compose git
 
# 启动Docker服务并设置开机自启
sudo systemctl enable --now docker
sudo usermod -aG docker $USER  # 注意：执行后需注销重新登录
 
# 验证Docker安装
docker --version  # 预期输出：Docker version 24.0.0+
docker-compose --version  # 预期输出：Docker Compose version v2.20.0+
 

第二阶段：LangSmith本地化部署

2.1 生成安全密钥

1
2
3
4
5
6
7
8

# 生成API Key Salt（用于加密API密钥）
openssl rand -base64 32
# 示例输出：U7MfWaDYNzzgMmvJXKn4Pl41mR5jJVHWrhq6c+6jngE=
 
# 生成JWT Secret（用于服务间认证）
openssl rand -base64 32
# 示例输出：8DvHV/Am3DVk6eWMiQxiLFZd0OTiCh2LgZ5IX2Wv658=
 

2.2 创建docker-compose配置文件

在项目根目录创建 docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

version: '3.8'

volumes:
  langsmith-db-data:
  langsmith-redis-data:
  langsmith-clickhouse-data:

services:
  langchain-frontend:
    image: docker.io/langchain/langsmith-frontend:0.11.4
    ports:
      - "1980:1980"
    environment:
      - VITE_BACKEND_AUTH_TYPE=none
      - VITE_BASIC_AUTH_ENABLED=false
    depends_on:
      - langchain-backend
  langchain-backend:
    image: docker.io/langchain/langsmith-backend:0.11.4
    environment:
      - PORT=1984
      - LANGCHAIN_ENV=local_docker
      - API_KEY_SALT=U7MfWaDYNzzgMmvJXKn4Pl41mR5jJVHWrhq6c+6jngE=  # 替换为实际生成值
      - POSTGRES_DATABASE_URI=postgres:postgres@langchain-db:5432/postgres
      - REDIS_DATABASE_URI=redis://langchain-redis:6379
      - CLICKHOUSE_HOST=langchain-clickhouse
      - CLICKHOUSE_PASSWORD=password
    ports:
      - "1984:1984"
    depends_on:
      langchain-db:
        condition: service_healthy
      langchain-redis:
        condition: service_healthy

  langchain-db:
    image: postgres:14.7
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=postgres
    volumes:
      - langsmith-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  langchain-redis:
    image: redis:7
    volumes:
      - langsmith-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  langchain-clickhouse:
    image: clickhouse/clickhouse-server:24.8
    environment:
      - CLICKHOUSE_PASSWORD=password
    volumes:
      - langsmith-clickhouse-data:/var/lib/clickhouse
      - ./users.xml:/etc/clickhouse-server/users.d/users.xml
    ports:
      - "8123:8123"

2.3 创建ClickHouse配置文件

在同一目录创建 users.xml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<clickhouse>
  <users>
    <default>
      <access_management>1</access_management>
      <profile>default</profile>
    </default>
  </users>
  <profiles>
    <default>
      <async_insert>1</async_insert>
      <async_insert_max_data_size>2000000</async_insert_max_data_size>
      <wait_for_async_insert>0</wait_for_async_insert>
    </default>
  </profiles>
</clickhouse>
 

2.4 启动LangSmith服务

1
2
3
4
5
6
7
8
9
10

# 启动所有服务（首次启动需下载镜像，耗时约5-10分钟）
docker-compose up -d
 
# 查看服务状态（确保所有服务都是healthy状态）
docker-compose ps
# 预期输出：所有服务状态为Up (healthy)
 
# 查看服务日志（如需调试）
docker-compose logs -f langchain-backend
 

http://localhost:1980

第三阶段：LangGraph集成与应用开发

3.1 创建LangGraph项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 创建虚拟环境
uv venv --python 3.12
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装LangGraph CLI
uv pip install -U "langgraph-cli[inmem]"

# 创建新项目
langgraph new ./langgraph-app --template 1  # 1表示基础聊天机器人模板

# 进入项目目录并安装依赖
cd langgraph-app
uv pip install -e .
 

3.2 配置本地LangSmith连接

.env

3.3 开发简单对话代理

app/graph.py

3.4 启动LangGraph服务

1
2
3
4
5
6
7

# 开发模式启动（支持热重载）
langgraph dev --port 2024
 
# 预期输出：
# INFO:     Uvicorn running on http://0.0.0.0:2024 (Press CTRL+C to quit)
# INFO:     Started reloader process [12345] using WatchFiles
 

第四阶段：离线调试环境搭建与验证

4.1 配置离线模式

offline-test.sh

4.2 编写离线测试代码

tests/offline_test.py

执行测试：

1
2
3
4
5
6
7
8
9
10

# 确保LangGraph服务已启动
python tests/offline_test.py
 
# 预期输出：
# Event type: metadata
# Content: {'run_id': '...', 'thread_id': '...'}
 
# Event type: chunk
# Content: {'messages': [{'role': 'assistant', 'content': 'LangGraph is a framework for building stateful, multi-actor applications with LLMs.'}]}
 

进阶技巧：企业级部署与优化

本地化vs云端服务：关键维度对比分析

数据安全与合规性强化方案

敏感数据保护

• • 传输加密：配置HTTPS加密通信

1
2
3
4
5
6
7
8
9
10

# 生成自签名证书（测试环境）
openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365
 
# 修改docker-compose.yml添加HTTPS配置
# 在langchain-frontend服务添加：
# volumes:
#   - ./cert.pem:/etc/nginx/cert.pem
#   - ./key.pem:/etc/nginx/key.pem
# 并修改Nginx配置启用HTTPS
 

• • 数据脱敏：在追踪系统中排除敏感字段

1
2
3
4
5
6
7
8
9

# 在LangGraph应用中配置脱敏规则
from langsmith import trace_config
 
config = trace_config(
    project_name="my-project",
    exclude_keys=["api_key", "password", "ssn"],  # 自动脱敏这些字段
    redact_pii=True  # 启用PII自动识别和脱敏
)
 

企业级扩展方案

多节点部署架构

对于高并发场景，推荐采用以下多节点架构：

部署命令示例：

1
2
3
4

# 使用Docker Compose扩展LangGraph实例
docker-compose up -d --scale langgraph-api=3
# 注意：需确保应用是无状态的，依赖存储在外部服务
 

监控告警配置

• • Prometheus监控集成：

1
2
3
4
5
6
7

# docker-compose.yml添加Prometheus服务
prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
  ports:
    - "9090:9090"

• • 关键指标告警规则（prometheus.yml）：

1
2
3
4
5
6
7
8
9
10
11
12

groups:
- name: langsmith_alerts
  rules:
  - alert: HighErrorRate
    expr: sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "High error rate on LangSmith API"
      description: "Error rate is above 5% for 2 minutes (current value: {{ $value }})"
 

常见问题排查与性能优化

故障排除指南

性能优化建议

• • 数据库优化：

1
2
3
4

-- PostgreSQL性能优化（在数据库容器中执行）
ALTER SYSTEM SET max_connections = 200;
ALTER TABLE runs SET (autovacuum_vacuum_scale_factor = 0.05);
 

• • 缓存策略：

1
2
3
4
5
6
7
8

# 在LangGraph中配置Redis缓存
from langgraph.cache import RedisCache
 
cache = RedisCache(redis_url="redis://localhost:6379/0")
 
# 应用到LLM调用
llm = ChatOpenAI(cache=cache)
 

• • 资源限制：为Docker容器设置合理的资源限制

1
2
3
4
5
6
7
8
9
10
11
12

# 在docker-compose.yml中添加
services:
  langchain-backend:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G
 

结语：本地化部署的价值与未来

LangSmith+LangGraph的本地化部署不仅解决了数据合规性问题，更构建了企业自主可控的LLM开发基础设施。通过本文介绍的部署流程，开发者可以在2小时内完成从环境搭建到离线调试的全流程，而企业则获得了定制化开发、数据安全和成本优化的多重收益。

随着LLM技术的深入发展，本地化部署将从"可选方案"变为"必备能力"。建议企业技术团队：

• • 建立专门的LLM基础设施团队，负责本地化环境的维护与优化- 制定明确的升级策略，平衡新功能获取与系统稳定性- 投入资源构建监控体系，确保AI应用的可观测性
  最终，自主可控的AI开发环境将成为企业在智能化时代保持竞争力的关键基础设施。

附录：常用命令速查表

#LangChain生态#LLM工程化#本地化部署#离线调试#企业级AI部署