LangChain 框架

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

2025 年 11 月 1 日

本地化部署LangSmith+LangGraph，解决企业数据合规与开发连续性难题，这份全流程指南助你轻松实现离线调试。核心内容： 1. 企业为何需要本地化部署LLM开发环境：数据合规与开发连续性的双重需求 2. 三种部署模式技术选型对比：从独立服务器到Kubernetes集群的适用场景分析 3. 实战四阶段部署指南：从环境准备到完整部署的详细操作步骤

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

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

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

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

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

部署模式	硬件要求	适用场景	核心优势	部署复杂度
独立服务器	4核8G	个人开发/小型团队	轻量快速，即开即用	⭐⭐☆☆☆
LangSmith完整部署	8核16G	中大型团队/企业研发	全功能监控，团队协作	⭐⭐⭐⭐☆
Kubernetes集群	16核64G+	企业级生产环境	高可用扩展，资源隔离	⭐⭐⭐⭐⭐

选型建议：开发测试环境优先选择独立服务器模式，生产环境推荐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云端服务：关键维度对比分析

维度	本地化部署	云端服务	企业决策建议
数据安全	数据完全自主控制	数据存储于第三方服务器	金融/医疗等敏感行业必须本地化
成本结构	一次性硬件投入+运维成本	按调用量付费，长期成本更高	月调用量>100万次建议本地化
可用性	依赖自建基础设施	99.9%+ SLA保障	关键业务需本地化+容灾方案
功能更新	手动升级维护	自动更新到最新版本	研发环境用云端尝鲜，生产环境本地化稳定版
定制能力	完全可控，可深度定制	受服务商API限制	需要定制工作流必须本地化

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

敏感数据保护

• 传输加密：配置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 }})"

常见问题排查与性能优化

故障排除指南

问题现象	可能原因	解决方案
LangSmith无法启动	端口冲突	执行 `netstat -tulpn` 查看占用端口，修改docker-compose.yml中的端口映射
追踪数据不显示	API密钥错误	在LangSmith UI重新生成API密钥，更新.env文件
服务启动后自动退出	内存不足	增加服务器内存或关闭不必要的服务，最低要求16GB
ClickHouse连接失败	密码错误	检查docker-compose.yml中的CLICKHOUSE_PASSWORD配置

性能优化建议

• 数据库优化：



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开发环境将成为企业在智能化时代保持竞争力的关键基础设施。

附录：常用命令速查表

操作	命令
启动LangSmith	docker-compose up -d
查看服务状态	docker-compose ps
查看日志	docker-compose logs -f [服务名]
重启服务	docker-compose restart [服务名]
备份数据	docker exec [db容器ID] pg_dump -U postgres > backup.sql
升级服务	docker-compose pull && docker-compose up -d

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

立即咨询 JOTO

JOTO 提供覆盖企业智能体规划与搭建、AI 平台私有化部署、RAG 知识工程、AI 安全治理、FDE 驻场共创及持续运营优化的全周期 AI 落地服务，帮助企业把验证中的 AI 能力转化为安全、可控、可持续迭代的生产力。联系 JOTO 获取 AI 落地咨询

想把这些做法用到你的业务里?

留下你的场景和痛点,我们帮你判断从哪一步开始。

联系我们

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

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

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

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

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

第二阶段：LangSmith本地化部署

2.1 生成安全密钥

2.2 创建docker-compose配置文件

2.3 创建ClickHouse配置文件

2.4 启动LangSmith服务

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

3.1 创建LangGraph项目

3.2 配置本地LangSmith连接

3.3 开发简单对话代理

3.4 启动LangGraph服务

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

4.1 配置离线模式

4.2 编写离线测试代码

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

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

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

敏感数据保护

企业级扩展方案

多节点部署架构

监控告警配置

常见问题排查与性能优化

故障排除指南

性能优化建议

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

立即咨询 JOTO

想把这些做法用到你的业务里?

开启企业级 AI 落地

填写需求单