BYOC 사용하기

BYOC 사용하기

트레이싱과 API 트래픽을 LangSmith BYOC 데이터 플레인으로 라우팅하는 방법을 다뤄요. 여러 엔드포인트로의 트레이싱과 각 서비스의 경로 접두사 포함해 설명합니다.

출처: 문서

본문

데이터 플레인이 활성화되면, 해당 워크스페이스의 모든 API 트래픽은 LangSmith Cloud 백엔드가 아닌 데이터 플레인 엔드포인트로 이동합니다. 이 페이지는 요청을 올바른 서비스로 라우팅하는 방법을 설명합니다.

LangSmith UI는 자동으로 처리합니다: 선택한 워크스페이스에 따라 올바른 데이터 플레인으로 라우팅합니다. 아래 지침은 자체 클라이언트 애플리케이션과 직접 API 호출에 적용됩니다.

조직, 데이터 플레인, 워크스페이스

BYOC 배포는 표준 LangSmith 리소스 계층에 한 단계를 추가합니다: 바로 데이터 플레인으로, 조직과 워크스페이스 사이에 위치합니다.

• 조직: 최상위 수준. 사용자, 역할, 결제, SSO 구성, API 키가 조직에 속하며 컨트롤 플레인에 있습니다.
• 데이터 플레인: 조직에 속하며 데이터의 물리적 분리를 나타냅니다. 조직은 여러 데이터 플레인을 가질 수 있으며, 각각 자체 AWS 계정과 지역에 있습니다.
• 워크스페이스: 정확히 하나의 데이터 플레인에 속하며, 워크스페이스 생성 시 선택합니다. 트레이스, 데이터셋, 실험 및 기타 애플리케이션 데이터가 워크스페이스에 있습니다.

데이터의 물리적 분리에는 데이터 플레인을, 데이터 플레인 안의 논리적 분리에는 워크스페이스를 사용하세요. 데이터 플레인을 나누는 일반적인 방법:

• 지역별, 예: us-east-1과 us-west-2 — 민감한 애플리케이션 데이터를 특정 지역에 유지.
• 환경 및 지역별, 예: prod us-east-1과 dev us-east-1 — 프로덕션과 개발 데이터를 별도의 AWS 계정에 보관.
• 사업 단위별 — 각 단위가 자체 AWS 계정을 소유할 때.

데이터 플레인 아래에서는 워크스페이스와 애플리케이션이 Cloud나 자체 호스팅과 동일하게 작동합니다. 자세한 내용은 관리 개요와 워크로드 격리를 참고하세요.

데이터 플레인 엔드포인트 찾기

각 데이터 플레인에는 기본 URL이 있습니다. Settings > Data Planes로 이동해 각 데이터 플레인, 상태, API URL을 확인하세요.

경고: 데이터 플레인은 기본적으로 비공개 엔드포인트로 프로비저닝되므로, 기본 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>"

경고: LANGSMITH_API_KEY를 대상 데이터 플레인 안의 워크스페이스에서 만들으세요. 트레이스는 테넌트 범위이므로, 다른 데이터 플레인(Cloud 워크스페이스 포함)의 워크스페이스에서 온 API 키는 거부됩니다.

완전하고 실행 가능한 예시는 관측성 빠른 시작을 따르고 위 환경 변수를 대체하세요.

API 요청 라우팅

기본 URL은 경로 접두사에 따라 다른 서비스로 라우팅합니다:

여러 엔드포인트로 트레이싱

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 아키텍처

더 알아보기

• BYOC 온보딩 절차는 BYOC onboarding 문서를 참고하세요.
• 아키텍처는 BYOC architecture 문서를 확인해 보세요.