在 Microsoft Azure 上运行 LangSmith 时 Microsoft Azure, self-hosted 模式会部署一个完整的 LangSmith 平台，包含可观测性功能。
本页面提供：
- - 初始设置步骤 用于部署到 AKS、配置托管服务以及设置身份验证。
- - Azure 特定的架构模式 以及参考图表。
- - 计算和网络指导 以及最佳实践。
- - 安全性和访问控制 Azure 部署建议。
初始设置
Deploy to Kubernetes
按照 Kubernetes 安装指南进行操作。LangSmith 在 Azure Kubernetes Service (AKS) 上进行了测试。
AKS 特定说明： - LangSmith 适用于标准 AKS 集群 - 使用 Azure Disk 存储类进行持久卷存储
Configure external services
对于生产环境部署，请连接到 Azure 托管服务：
Azure Blob Storage
将追踪数据存储在 Azure Blob 中
Azure Database
PostgreSQL 数据库
Azure Cache
用于缓存的 Redis
ClickHouse Cloud
分析数据库
Set up authentication
使用 Azure Workload Identity 对 LangSmith Pod 进行 Azure 服务身份验证。
关键页面： - Azure Blob 托管标识 - Azure Database Entra 身份验证 - Azure Cache Entra 身份验证
完成这些初始设置步骤后，您可以查看下面的完整 Azure 架构和最佳实践。
参考架构
我们建议使用 Azure 的托管服务来提供可扩展、安全且有弹性的平台。以下架构适用于自托管和混合部署。
| 组件 | 如何安装 | |
|---|---|---|
| **LangSmith Helm 版本** | Frontend, backend, queue, platform backend, Playground, ACE, and optionally the LangSmith Deployment control/data plane | One helm upgrade --install 来自 langchain/langsmith chart |
| **您提供** | AKS、PostgreSQL、托管 Redis、Blob Storage、Key Vault、入口和 ClickHouse | 在安装 LangSmith 之前使用您的 IaC 工具（Terraform、ARM 模板或 Azure 门户） |
安装顺序： 配置 Azure 基础设施 → 配置或订阅 ClickHouse → 配置 Entra ID 和工作负载标识 → 运行 helm upgrade --install。LangSmith Deployment、Fleet、Insights 和 Chat 通过同一 Helm 版本启用，而非单独安装。
合规范围： 对 LangSmith chart 及其容器镜像进行一次应用审查，加上对每个托管资源进行标准 Azure 服务审查。ClickHouse Cloud 需要增加一次第三方 SaaS 审查。
- 客户端接口：用户通过 Web 浏览器或 LangChain SDK 与 LangSmith 交互。所有流量终止于 Azure Load Balancer ，然后路由到集群内的前端 (NGINX) AKS ，如有必要，再路由到集群内的其他服务。
- 存储服务：平台需要持久存储来存放追踪、元数据和缓存。在 Azure 上，推荐使用的服务是：
- - **Azure Database for PostgreSQL (Flexible Server)** 用于事务数据（如运行、项目）。Azure 的高可用性选项会在另一可用区配置备用副本；数据同步提交到主服务器和备用服务器。LangSmith 要求 PostgreSQL 14 或更高版本。
- - **Azure Managed Redis** 用于队列和缓存。最佳实践包括存储小值并将大对象拆分为多个键，使用管道化来最大化吞吐量，并确保客户端和服务器位于同一区域。您也可以使用 Azure Cache for Redis，以单实例或集群模式运行。LangSmith 要求 Redis OSS 5 或更高版本。
- ClickHouse 用于高容量追踪分析。我们建议使用 外部托管的 ClickHouse 解决方案。如果由于安全或合规原因不可行，请使用开源 operator 在 AKS 上部署 ClickHouse 集群。确保跨 可用区 进行复制以确保持久性。混合部署不需要 ClickHouse。
- - **Azure Blob Storage** 用于大型制品。使用冗余存储配置（如读取访问地理冗余存储或读取访问地理区域冗余存储），并设计应用程序在中断期间从辅助区域读取。
Azure 上的计算和网络
Azure Kubernetes Service (AKS)
AKS 是生产环境部署的推荐计算平台。本节概述了规划设置时的关键考虑因素。
网络模型
使用 Azure CNI 网络用于生产集群。该模型将集群集成到现有虚拟网络中，为每个 Pod 和节点分配 IP 地址，允许直接连接到本地或其他 Azure 服务。确保子网有足够的 IP 用于节点和 Pod，避免地址范围重叠，并为扩展事件分配额外的 IP 空间。
入口和负载均衡
Use Kubernetes Ingress resources and controllers to distribute HTTP/HTTPS traffic. Ingress controllers operate at layer 7 and can route traffic based on URL paths and handle TLS termination. They reduce the number of public IP addresses compared to layer-4 load balancers. Use the 应用程序路由附加组件 对于与托管 NGINX 入口控制器集成的 Azure DNS 和 密钥保管库 配合使用以获取 SSL 证书。
Web 应用程序防火墙 (WAF)
为了进一步防护攻击，请部署 WAF 例如 Azure 应用程序网关。WAF 使用 OWASP 规则过滤流量，并可在流量到达 AKS 集群之前终止 TLS。
网络策略
应用 Kubernetes 网络策略 来限制 Pod 间的流量，并减少受侵害工作负载的影响。创建集群时启用网络策略支持，并根据应用程序连接需求设计规则。
高可用性
跨 可用区 配置节点池，并为所有部署使用 Pod 中断预算 (PDB) 和多个副本。设置 Pod 资源请求和限制； AKS 资源管理最佳实践 建议设置 CPU 和内存限制，以防止 Pod 耗尽所有资源。使用 集群自动缩放器 和 垂直 Pod 自动缩放器 来自动扩展节点池和调整 Pod 资源。
网络和身份
虚拟网络集成
将 AKS 部署到其自己的 虚拟网络 中，并为集群、数据库、Redis 和存储端点创建单独的子网。使用 专用链接 和 服务终结点 来保持流量在您的虚拟网络内，避免暴露在公共互联网上。
身份验证
将 LangSmith 与 Microsoft Entra ID (Azure AD) 集成以实现单点登录。使用 Azure AD OAuth2 进行持有者令牌身份验证，并分配角色以控制对 UI 和 API 的访问。
存储和数据服务
Azure Database for PostgreSQL
高可用性
使用 灵活服务器 并启用高可用性模式。Azure 在同一可用区（同区）或跨可用区（区域冗余）内配置备用副本。数据会同步提交到主服务器和备用服务器，确保已提交的数据不会丢失。区域冗余配置将备用副本放置在不同的可用区中，以防止单区故障，但可能会增加写入延迟。
备份和灾难恢复
启用 自动备份 并配置异地冗余备份存储，以防止区域性故障。对于关键应用程序，请在次要区域创建只读副本。
缩放
选择与您工作负载匹配的适当 SKU；灵活服务器允许独立扩展计算和存储。通过以下方式监控指标和配置警报 Azure Monitor.
Azure 托管 Redis
持久性和冗余
选择提供复制和持久性的层级。配置 Redis 持久性或数据备份以确保耐用性。对于高可用性，请使用 主动异地复制 或区域冗余缓存，具体取决于层级。
Azure 上的 ClickHouse
ClickHouse 用于分析工作负载（追踪和反馈）。如果无法使用外部托管解决方案，请使用 Helm 或官方运算符在 AKS 上部署 ClickHouse 集群。为提高弹性，请在节点和可用性区域之间复制数据。考虑使用 Azure 磁盘 作为本地存储，并将其挂载为 StatefulSets。
Azure Blob 存储
冗余
根据您的恢复目标选择冗余配置。使用 读取访问异地冗余 (RA-GRS) 或异地区域冗余 (RA-GZRS) 存储 并设计应用程序以在主区域中断期间将读取切换到辅助区域。
命名和分区
使用可改善跨分区负载均衡的命名约定，并规划最大并发客户端数量。保持在 Azure 的可伸缩性和容量目标范围内，必要时可将数据分区到多个存储账户。
网络
通过以下方式访问 blob 存储 私有终结点 或使用 SAS 令牌和 CORS 规则启用直接客户端访问。
安全性和访问控制
Azure Key Vault
每个应用程序和环境使用单独的保管库
将数据库连接字符串和 API 密钥等密钥存储在 Azure Key Vault中。为每个应用程序和环境（开发、测试、生产）使用专用保管库，以限制安全漏洞的影响。
访问控制
使用 RBAC 权限模型 在保管库范围分配角色并限制对所需主体的访问。使用 Private Link 和防火墙限制网络访问。
数据保护和日志记录
启用 软删除和清除保护 以防止意外删除。开启日志记录并为 Key Vault 访问事件配置警报。
网络安全
入口隔离
仅通过入口控制器或 WAF 公开前端服务。其他服务应为内部服务，并通过集群网络进行通信。
RBAC 和 Pod 安全性
使用 Kubernetes RBAC 控制谁可以部署、修改或读取资源。启用 Pod 安全准入 来强制执行基准、受限或特权配置文件。
密钥管理
使用 Key Vault 将密钥挂载到 pod 中 CSI Secret Store。避免在环境变量或配置文件中存储密钥。
可观测性和监控
配置您的 LangSmith 实例以 导出遥测数据 以便您可以使用 Azure 的服务来监控它。
Azure Monitor
使用 Azure Monitor for metrics, logs, and alerting. Proactive monitoring involves configuring alerts on key signals like node CPU/memory utilization, pod status, and service latency. Azure Monitor alerts notify you when predefined thresholds are exceeded.
托管 Prometheus 和 Grafana
启用 Azure Monitor 托管的 Prometheus 来收集 Kubernetes 指标。结合 Grafana 仪表板 进行可视化。定义服务级别目标（SLO）并相应配置警报。
容器洞察
安装 容器洞察 以从 AKS 节点和 pod 捕获日志和指标。使用 Azure Log Analytics 工作区 来查询和分析日志。
应用程序日志记录
Ensure LangSmith services emit logs to stdout/stderr and forward them via Fluent Bit 或 Azure Monitor 代理。
## 持续集成 - 管理 LangSmith 部署 的首选方法是创建 CI 流程来构建 Agent Server 镜像并将其推送到 Azure Container Registry。在 PR 合并后将新版本部署到 staging 或生产环境之前，为拉取请求创建测试部署。