LangSmith+LangGraph本地化部署与离线调试全流程
推荐语
本地化部署LangSmith+LangGraph，解决企业数据合规与开发连续性难题，这份全流程指南助你轻松实现离线调试。
核心内容：
1. 企业为何需要本地化部署LLM开发环境：数据合规与开发连续性的双重需求
2. 三种部署模式技术选型对比：从独立服务器到Kubernetes集群的适用场景分析
3. 实战四阶段部署指南：从环境准备到完整部署的详细操作步骤
杨芳贤
53AI创始人/腾讯云(TVP)最具价值专家
2025年3月，某金融科技公司因使用云端LangSmith服务处理客户敏感数据，违反《数据安全法》第21条"关键信息基础设施运营者在中华人民共和国境内运营中收集和产生的个人信息和重要数据应当在境内存储"的规定，被监管部门处以200万元罚款。该案例揭示了LLM开发工具云端部署在金融、医疗等敏感行业的合规风险。
无独有偶，另一AI创业公司在使用云端服务时遭遇API调用失败，导致整个开发团队停滞3小时。这两个真实事件凸显了本地化部署的迫切性——数据主权与开发连续性已成为企业LLM工程化的核心诉求。
LangChain生态提供了三种本地化部署方案，我们需要根据团队规模和业务需求选择合适的路径：
选型建议：开发测试环境优先选择独立服务器模式，生产环境推荐Kubernetes部署。本文将重点讲解最具普适性的"独立服务器+LangSmith监控"组合方案，兼顾开发效率与可观测性。
硬件要求：
# Ubuntu系统依赖安装
sudoapt update &&sudoapt install -y python3.12 python3.12-venv docker.io docker-compose git
# 启动Docker服务并设置开机自启
sudosystemctlenable--now docker
sudousermod -aG docker$USER# 注意：执行后需注销重新登录
# 验证Docker安装
docker --version# 预期输出：Docker version 24.0.0+
docker-compose --version# 预期输出：Docker Compose version v2.20.0+
# 生成API Key Salt（用于加密API密钥）
openssl rand -base6432
# 示例输出：U7MfWaDYNzzgMmvJXKn4Pl41mR5jJVHWrhq6c+6jngE=
# 生成JWT Secret（用于服务间认证）
openssl rand -base6432
# 示例输出：8DvHV/Am3DVk6eWMiQxiLFZd0OTiCh2LgZ5IX2Wv658=
在项目根目录创建docker-compose.yml：
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"
在同一目录创建users.xml：
<clickhouse>
<users>
<default>
<access_management>1access_management>
<profile>defaultprofile>
default>
users>
<profiles>
<default>
<async_insert>1async_insert>
<async_insert_max_data_size>2000000async_insert_max_data_size>
<wait_for_async_insert>0wait_for_async_insert>
default>
profiles>
clickhouse>
# 启动所有服务（首次启动需下载镜像，耗时约5-10分钟）
docker-compose up -d
# 查看服务状态（确保所有服务都是healthy状态）
docker-compose ps
# 预期输出：所有服务状态为Up (healthy)
# 查看服务日志（如需调试）
docker-compose logs -f langchain-backend
http://localhost:1980
# 创建虚拟环境
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表示基础聊天机器人模板
# 进入项目目录并安装依赖
cdlanggraph-app
uv pip install -e .
.env
app/graph.py
# 开发模式启动（支持热重载）
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
offline-test.sh
tests/offline_test.py
执行测试：
# 确保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.'}]}
# 生成自签名证书（测试环境）
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
# 在LangGraph应用中配置脱敏规则
fromlangsmithimporttrace_config
config = trace_config(
project_name="my-project",
exclude_keys=["api_key","password","ssn"],# 自动脱敏这些字段
redact_pii=True# 启用PII自动识别和脱敏
)
对于高并发场景，推荐采用以下多节点架构：
部署命令示例：
# 使用Docker Compose扩展LangGraph实例
docker-compose up -d --scale langgraph-api=3
# 注意：需确保应用是无状态的，依赖存储在外部服务
# docker-compose.yml添加Prometheus服务
prometheus:
image:prom/prometheus
volumes:
-./prometheus.yml:/etc/prometheus/prometheus.yml
ports:
-"9090:9090"
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 }})"
| ||
-- PostgreSQL性能优化（在数据库容器中执行）
ALTERSYSTEMSETmax_connections=200;
ALTER TABLErunsSET(autovacuum_vacuum_scale_factor=0.05);
# 在LangGraph中配置Redis缓存
fromlanggraph.cacheimportRedisCache
cache = RedisCache(redis_url="redis://localhost:6379/0")
# 应用到LLM调用
llm = ChatOpenAI(cache=cache)
# 在docker-compose.yml中添加
services:
langchain-backend:
deploy:
resources:
limits:
cpus:'4'
memory:8G
reservations:
cpus:'2'
memory:4G
LangSmith+LangGraph的本地化部署不仅解决了数据合规性问题，更构建了企业自主可控的LLM开发基础设施。通过本文介绍的部署流程，开发者可以在2小时内完成从环境搭建到离线调试的全流程，而企业则获得了定制化开发、数据安全和成本优化的多重收益。
随着LLM技术的深入发展，本地化部署将从"可选方案"变为"必备能力"。建议企业技术团队：
附录：常用命令速查表
#LangChain生态#LLM工程化#本地化部署#离线调试#企业级AI部署
langchainlangchain 是干什么的langchain 本地知识库
