在 Azure 上自托管 LangSmith

在 Microsoft Azure 上运行 LangSmith 时，自托管模式会部署一个具备可观测性功能的完整 LangSmith 平台。 本页面介绍：

• 用于部署到 AKS、配置托管服务和设置身份验证的初始设置步骤。
• Azure 专属架构模式和参考架构图。
• Azure 上的计算与网络指南及最佳实践。
• Azure 部署的安全性与访问控制建议。

​

初始设置

完成这些初始设置步骤后，你可以查看下面完整的 Azure 架构和最佳实践。

​

参考架构

我们建议使用 Azure 托管服务来提供可扩展、安全且高可靠的平台。以下架构同时适用于自托管和混合部署。 **安装顺序：**配置 Azure 基础设施 → 配置或订阅 ClickHouse → 配置 Entra ID 和 Workload Identity → 执行 helm upgrade --install。LangSmith Deployment、Fleet、Insights 和 Chat 通过同一个 Helm 发布版本启用，而不是分别安装。 **合规范围：**对 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 版本为 5 或更高。
  • ClickHouse 用于对大量跟踪数据进行分析。我们建议使用外部托管的 ClickHouse 解决方案。如果出于安全或合规原因无法采用该方案，可以使用开源运算符在 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 流量。入口控制器运行在第 7 层，可以根据 URL 路径路由流量并处理 TLS 终止。与第 4 层负载均衡器相比，它们可以减少所需的公共 IP 地址数量。使用应用程序路由附加组件，以获得与 Azure DNS 和 Key Vault 集成的托管 NGINX 入口控制器，用于 SSL 证书管理。

​

Web 应用程序防火墙（WAF）

如需进一步防范攻击，请部署 WAF，例如 Azure Application Gateway。WAF 使用 OWASP 规则过滤流量，并可以在流量到达 AKS 集群之前终止 TLS。

​

网络策略

应用 Kubernetes 网络策略来限制 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 或官方运算符在 AKS 上部署 ClickHouse 集群。为了提高弹性，请在多个节点和可用性区域之间复制数据。可以考虑使用 Azure Disks 进行本地存储，并将其挂载为 StatefulSets。

​

Azure Blob Storage

​

冗余

根据恢复目标选择冗余配置。使用读取访问异地冗余（RA-GRS）或异地区域冗余（RA-GZRS）存储，并设计应用程序，使其在主区域发生故障时将读取请求切换到辅助区域。

​

命名与分区

使用有助于在分区之间实现负载均衡的命名约定，并为最大并发客户端数量做好规划。遵守 Azure 的可扩展性和容量目标，并在必要时将数据分布到多个存储帐户中。

​

网络

通过专用终结点访问 Blob Storage，或使用 SAS 令牌和 CORS 规则来启用客户端直接访问。

​

安全性与访问控制

​

Azure Key Vault

​

为每个应用程序和环境使用独立的保管库

将数据库连接字符串和 API 密钥等机密存储在 Azure Key Vault 中。为每个应用程序和环境（dev、test、prod）使用专用保管库，以限制安全漏洞的影响范围。

​

访问控制

使用 RBAC 权限模型在保管库范围分配角色，并将访问权限限制在必需的主体上。使用 Private Link 和防火墙限制网络访问。

​

数据保护与日志记录

启用软删除和清除保护，以防止意外删除。开启日志记录，并为 Key Vault 访问事件配置警报。

​

网络安全

​

入口隔离

仅通过入口控制器或 WAF 暴露前端服务。其他服务应保持内部访问，并通过集群网络进行通信。

​

RBAC 与 Pod 安全

使用 Kubernetes RBAC控制谁可以部署、修改或读取资源。启用 Pod 安全准入，以强制执行基线、受限或特权配置文件。

​

机密管理

使用 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 代理转发日志。

​

持续集成

• 管理 LangSmith 部署的首选方法是创建 CI 流程，构建 Agent Server 镜像并将其推送到 Azure Container Registry。针对拉取请求创建测试部署，并在 PR 合并��将新修订版本部署到预发布环境或生产环境。

---