主题
在 Azure 上自托管 LangSmith
在 Microsoft Azure 上运行 LangSmith 时，自托管模式会部署一个具有可观测性功能的完整 LangSmith 平台。
本页提供：
- 用于部署到 AKS、配置托管服务以及设置身份认证的初始设置步骤。
- Azure 专属架构模式和参考图。
- 计算与网络指南和最佳实践。
- 针对 Azure 部署的安全与访问控制建议。
NOTE
LangChain 发布了可用于生产环境的 Azure Terraform 模块，它们在一个工作流中预置 AKS、Azure Database for PostgreSQL、Azure Managed Redis、Blob Storage 和 Key Vault。请从使用 Terraform 部署概览开始，以便在 Terraform 路径与仅 Helm 路径之间进行选择。
初始设置
Deploy to Kubernetes
请遵循 Kubernetes 安装指南。LangSmith 已在 Azure Kubernetes Service (AKS) 上测试。
AKS 专属说明：
- LangSmith 可与标准的 AKS 集群配合使用
- 使用 Azure Disk 存储类来创建持久卷
Configure external services
Set up authentication
使用 Azure Workload Identity 让 LangSmith pod 向 Azure 服务进行身份认证。
关键页面：
完成这些初始设置步骤后，你可以查看下方完整的 Azure 架构和最佳实践。
参考架构
我们建议使用 Azure 的托管服务来提供可扩展、安全且有弹性的平台。以下架构适用于自托管和混合部署。
| 组件 | 安装方式 | |
|---|---|---|
| LangSmith Helm release | 前端、后端、队列、平台后端、Playground、ACE，以及可选的 LangSmith Deployment 控制面/数据面 | 从 langchain/langsmith chart 执行一次 helm upgrade --install |
| 由你预置 | AKS、PostgreSQL、Managed Redis、Blob Storage、Key Vault、入口和 ClickHouse | 在安装 LangSmith 之前，使用你的 IaC 工具（Terraform、ARM templates 或 Azure portal） |
安装顺序： 预置 Azure 基础设施 → 预置或订阅 ClickHouse → 配置 Entra ID 和 Workload Identity → 运行 helm upgrade --install。LangSmith Deployment、Fleet、Insights 和 Chat 通过同一个 Helm release 启用，而不是作为单独的安装。
合规审查范围： 对 LangSmith chart 及其容器镜像进行一次应用审查，并对每个托管资源进行标准的 Azure 服务审查。ClickHouse Cloud 会增加一次第三方 SaaS 审查。
- 客户端接口：用户通过 Web 浏览器或 LangChain SDK 与 LangSmith 交互。所有流量都终止于 Azure Load Balancer，并被路由到 AKS 集群内的前端 (NGINX)，然后根据需要路由到集群内的其他服务。
- 存储服务：平台需要持久化存储来存放追踪、元数据和缓存。在 Azure 上，推荐的服务有： *
Azure Database for PostgreSQL (Flexible Server) 用于事务性数据（例如运行、项目）。Azure 的高可用性选项会在另一个可用区预置一个备用副本；数据会同步提交到主服务器和备用服务器。LangSmith 要求 PostgreSQL 14 或更高版本。 *
Azure Managed Redis 用于队列和缓存。最佳实践包括存储小值并将大型对象拆分为多个键、使用管道化以最大化吞吐量，以及确保客户端和服务器位于同一区域。你还可以使用 Azure Cache for Redis，以单实例或集群模式运行。LangSmith 要求 Redis OSS 6.2 或更高版本。 *
ClickHouse 用于对追踪进行高吞吐量分析。我们建议使用外部托管的 ClickHouse 解决方案。如果出于安全或合规原因而无法采用该方案，请使用开源 operator 在 AKS 上部署 ClickHouse 集群。为确保持久性，请在可用区之间进行复制。混合部署不需要 Clickhouse。 *
Azure Blob Storage 用于存储大型产物。使用冗余存储配置，例如读取访问异地冗余 (RA-GRS) 或地理区域冗余 (RA-GZRS) 存储，并设计应用使其在发生故障时从次要区域读取。
Azure 上的计算与网络
Azure Kubernetes Service (AKS)
AKS 是生产部署推荐的计算平台。本节概述规划你的设置时的关键考虑因素。
网络模型
生产集群请使用 Azure CNI 网络。此模型会将集群集成到现有的虚拟网络中，为每个 pod 和节点分配 IP 地址，并允许直接连接到本地部署或其他 Azure 服务。确保子网有足够的 IP 供节点和 pod 使用，避免地址范围重叠，并为扩容事件分配额外的 IP 空间。
入口与负载均衡
使用 Kubernetes Ingress 资源和控制器来分发 HTTP/HTTPS 流量。Ingress 控制器在第 7 层运行，可以基于 URL 路径路由流量并处理 TLS 终止。与第 4 层负载均衡器相比，它们可减少公网 IP 地址的数量。对于托管的 NGINX ingress 控制器，使用应用程序路由加载项，并与 Azure DNS 以及用于 SSL 证书的 Key Vault 集成。
Web Application Firewall (WAF)
为获得额外的攻击防护，请部署 WAF，例如 Azure Application Gateway。WAF 使用 OWASP 规则过滤流量，并可在流量到达 AKS 集群之前终止 TLS。
网络策略
应用 Kubernetes 网络策略来限制 pod 到 pod 的流量，并减少受损工作负载的影响。在创建集群时启用网络策略支持，并基于应用连接性设计规则。
高可用性
跨可用区配置节点池，并为所有部署使用 Pod Disruption Budgets (PDB) 和多个副本。设置 pod 资源请求和限制；AKS 资源管理最佳实践建议设置 CPU 和内存限制，以防止 pod 占用所有资源。使用 Cluster Autoscaler 和 Vertical Pod Autoscaler 来自动扩缩节点池并调整 pod 资源。
网络与标识
虚拟网络集成
将 AKS 部署到其自身的虚拟网络中，并为集群、数据库、Redis 和存储终结点创建单独的子网。使用 Private Link 和服务终结点将流量保持在虚拟网络内，避免暴露到公共互联网。
身份认证
将 LangSmith 与 Microsoft Entra ID（Azure AD）集成以实现单点登录。使用 Azure AD OAuth2 处理 bearer token，并分配角色以控制对 UI 和 API 的访问。
存储与数据服务
Azure Database for PostgreSQL
高可用性
使用具有高可用性模式的 Flexible Server。Azure 会在同一可用区内（分区）或跨可用区（区域冗余）预置一个备用副本。数据会同步提交到主服务器和备用服务器，确保已提交的数据不会丢失。区域冗余配置会将备用副本放在不同的可用区，以防止可用区故障，但可能会增加写入延迟。
备份与灾难恢复
启用自动备份，并配置异地冗余备份存储，以防范区域范围的故障。对于关键应用，请在次要区域创建只读副本。
扩缩容
选择与你的工作负载相匹配的适当 SKU；Flexible Server 允许独立扩缩计算和存储。通过 Azure Monitor 监控指标并配置告警。
Azure Managed Redis
持久化与冗余
选择提供复制和持久化的层级。为实现持久性，请配置 Redis 持久化或数据备份。为实现高可用性，请根据层级使用主动地理复制或区域冗余缓存。
Azure 上的 ClickHouse
ClickHouse 用于分析型工作负载（追踪和反馈）。如果无法使用外部托管的解决方案，请使用 Helm 或官方 operator 在 AKS 上部署 ClickHouse 集群。为增强弹性，请在节点和可用区之间复制数据。考虑使用 Azure Disks 作为本地存储，并以 StatefulSets 的形式挂载它们。
Azure Blob Storage
冗余
根据你的恢复目标选择冗余配置。使用读取访问异地冗余 (RA-GRS) 或地理区域冗余 (RA-GZRS) 存储，并设计应用使其在主区域发生故障时将读取切换到次要区域。
命名与分区
使用可改善跨分区负载均衡的命名约定，并为最大并发客户端数量做好规划。不要超出 Azure 的可扩展性和容量目标，如有必要，将数据分区到多个存储账户中。
网络
通过专用终结点访问 blob 存储，或使用 SAS token 和 CORS 规则来实现客户端直接访问。
安全与访问控制
Azure Key Vault
为每个应用和环境使用单独的保管库
将数据库连接字符串和 API key 等机密存储在 Azure Key Vault 中。为每个应用和环境（dev、test、prod）使用专用保管库，以限制安全漏洞的影响。
访问控制
使用 RBAC 权限模型在保管库范围分配角色，并将访问限制为所需的主体。使用 Private Link 和防火墙限制网络访问。
数据保护与日志记录
启用软删除和清除保护以防止意外删除。开启日志记录，并为 Key Vault 访问事件配置告警。
网络安全
入口隔离
仅通过 ingress 控制器或 WAF 暴露前端服务。其他服务应为内部服务，并通过集群网络进行通信。
RBAC 与 pod 安全
使用 Kubernetes RBAC 来控制谁可以部署、修改或读取资源。启用 pod 安全准入以强制执行 baseline、restricted 或 privileged 配置文件。
机密管理
使用 CSI Secret Store 将 Key Vault 中的机密挂载到 pod 中。避免将机密存储在环境变量或配置文件中。
可观测性与监控
配置你的 LangSmith 实例以导出遥测数据，这样你就可以使用 Azure 的服务来监控它。
Azure Monitor
使用 Azure Monitor 进行指标、日志和告警。主动监控包括针对节点 CPU/内存利用率、pod 状态和服务延迟等关键信号配置告警。当超过预定义阈值时，Azure Monitor 告警会通知你。
托管 Prometheus 与 Grafana
启用 Azure Monitor 托管 Prometheus 来收集 Kubernetes 指标。将其与 Grafana 仪表盘结合使用以实现可视化。定义服务级别目标 (SLO) 并相应地配置告警。
Container Insights
安装 Container Insights 以捕获 AKS 节点和 pod 的日志与指标。使用 Azure Log Analytics 工作区查询和分析日志。
应用日志记录
确保 LangSmith 服务将日志输出到 stdout/stderr，并通过 Fluent Bit 或 Azure Monitor agent 转发它们。
持续集成
- 管理 LangSmith 部署的首选方法是创建一个 CI 流程，构建 Agent Server 镜像并将其推送到 Azure Container Registry。为 pull request 创建一个测试部署，然后在 PR 合并时将新修订部署到预发布或生产环境。