BYOC 使用

将追踪和 API 流量路由到 LangSmith BYOC 数据平面，包括向多个端点发送追踪，以及每项服务的路径前缀。

一旦你的数据平面处于活动状态，其工作区的所有 API 流量都会发往数据平面端点，而不再发往 LangSmith Cloud 后端。本页说明如何将请求路由到正确的服务。

LangSmith UI 会自动处理这一点：它会根据你选择的工作区路由到正确的数据平面。以下指南适用于你自己的客户端应用程序和直接 API 调用。

组织、数据平面和工作区

BYOC 部署在标准 LangSmith 资源层级上增加了一个层级：数据平面，它位于组织和工作区之间。

• 组织：最高层级。用户、角色、计费、SSO 配置和 API 密钥都属于组织，并位于控制平面中。
• 数据平面：属于一个组织，代表数据的物理隔离。一个组织可以有多个数据平面，每个都位于其各自的 AWS 账户和区域中。
• 工作区：恰好属于一个数据平面，你在创建工作区时选择该数据平面。追踪、数据集、实验和其他应用程序数据都存放在工作区中。

使用数据平面实现数据的物理隔离，使用工作区实现数据平面内的逻辑隔离。划分数据平面的常见方式有：

• 按区域，例如 us-east-1 和 us-west-2，将敏感应用程序数据保留在特定区域。
• 按环境和区域，例如生产 us-east-1 和开发 us-east-1，将生产数据和开发数据保存在不同的 AWS 账户中。
• 按业务部门，当每个部门都拥有自己的 AWS 账户时。

在数据平面之下，工作区和应用程序的运作方式与 Cloud 或自托管上相同。有关更多信息，请参阅管理概览和工作负载隔离。

查找你的数据平面端点

每个数据平面都有一个基础 URL。导航到 Settings > Data Planes 以查看你的每个数据平面、其状态及其 API URL。

WARNING

数据平面默认以私有端点预置，因此你需要私有连接才能访问基础 URL，例如 Tailscale、AWS PrivateLink 或 VPC 对等连接。

追踪到数据平面

要将追踪发送到位于你数据平面中的工作区，请将 LangSmith SDK 指向数据平面端点，并使用限定到该数据平面中某个工作区的 API 密钥进行身份认证：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<your-api-key>"
export LANGSMITH_ENDPOINT="https://<data_plane_host>"

WARNING

从目标数据平面内的工作区创建 LANGSMITH_API_KEY。追踪是按租户限定范围的，因此来自不同数据平面上工作区（包括 Cloud 工作区）的 API 密钥会被拒绝。

如需完整、可运行的示例，请按照可观测性快速入门操作，并替换上面的环境变量。

路由 API 请求

基础 URL 会根据路径前缀路由到不同的服务：

服务	路径前缀	示例
LangSmith	/api	https://<data_plane_host>/api/v1/sessions
LangSmith Deployment	/api-host	https://<data_plane_host>/api-host/v2/deployments
LLM Gateway	/gateway	https://<data_plane_host>/gateway/v1/chat/completions

追踪到多个端点

使用这些模式可以同时追踪到 Cloud 和数据平面，或追踪到多个数据平面。

双写两个端点

设置 LANGSMITH_RUNS_ENDPOINTS 以写入多个端点：

export LANGSMITH_RUNS_ENDPOINTS='[
  {"api_url": "https://aws.api.smith.langchain.com", "api_key": "ls__key1", "project_name": "project-cloud"},
  {"api_url": "https://<data_plane_host>", "api_key": "ls__key2", "project_name": "project-byoc"}
]'

在应用程序逻辑中选择目标

要在运行时决定追踪到哪里，请为每个端点创建一个客户端并在它们之间进行选择：

import os

from langsmith import Client, traceable, tracing_context

CLOUD_ENDPOINT = "https://aws.api.smith.langchain.com"
BYOC_ENDPOINT = "https://<data_plane_host>"

def require_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value

cloud_client = Client(
    api_key=require_env("LANGSMITH_CLOUD_API_KEY"),
    api_url=CLOUD_ENDPOINT,
    workspace_id=os.getenv("LANGSMITH_CLOUD_WORKSPACE_ID"),
)

byoc_client = Client(
    api_key=require_env("LANGSMITH_BYOC_API_KEY"),
    api_url=BYOC_ENDPOINT,
    workspace_id=os.getenv("LANGSMITH_BYOC_WORKSPACE_ID"),
)

def get_workspace_routing(tenant_id: str):
    """Determine the tracing destination based on application routing logic."""
    if tenant_id.startswith("byoc_"):
        return byoc_client, os.getenv("LANGSMITH_BYOC_PROJECT", "byoc-customer-project")
    return cloud_client, os.getenv("LANGSMITH_CLOUD_PROJECT", "cloud-customer-project")

@traceable
def run_agent_workflow(query: str):
    return f"Processed: {query}"

def handle_request(tenant_id: str, query: str):
    client, project_name = get_workspace_routing(tenant_id)

    with tracing_context(enabled=True, client=client, project_name=project_name):
        return run_agent_workflow(query)

另请参阅

• BYOC 入门
• BYOC 架构

---