추가 LangSmith 기능 활성화

추가 LangSmith 기능 활성화

셀프 호스팅 LangSmith 인스턴스에서 LangSmith Deployment, Fleet, Insights, Chat, Sandboxes 및 Engine을 활성화해요.

기본 LangSmith 플랫폼에 더해, LangSmith Self-hosted에서 다음 기능을 활성화할 수 있어요:

  • LangSmith Deployment 는 컨트롤 플레인과 데이터 플레인을 추가해서 LangSmith UI를 통해 직접 에이전트와 애플리케이션을 배포, 확장, 관리할 수 있게 해요. 전체 UI 기반 설정이 필요 없다면, 가벼운 대안인 독립 실행형 서버를 참고하세요.
  • Fleet 은 코드 없이 LangSmith 안에서 직접 AI 에이전트를 만들고, 배포하고, 관리할 수 있게 해요.
  • Insights 는 LangSmith 안의 트레이스와 애플리케이션 데이터에 대한 AI 기반 분석을 제공해요.
  • Chat 은 트레이스, 스레드, 프롬프트, 실험 결과를 분석하는 데 도움이 되는 워크스페이스 내 채팅 경험을 제공해요.
  • Sandboxes 는 사용자가 LangSmith에서 코드를 실행하고, 임시 서비스를 노출하고, 메모리 스냅샷을 만들 수 있게 해요.
  • Engine 은 추적 프로젝트에서 반복되는 이슈를 찾아 소스 코드에 대해 진단하고 수정 사항을 제안해요. Engine은 Sandboxes를 필요로 하며 셀프 호스팅의 Engine에서 설치돼요.

이러한 기능은 Enterprise 요금제가 필요해요. 자세한 내용은 데모 요청을 하세요.

출처: 문서

본문

사전 요구 사항

  1. 기본 LangSmith 플랫폼 설치: 계속하기 전에 Kubernetes 설치 가이드를 따라 기본 LangSmith 플랫폼을 설치하세요.

  2. KEDA 설치: 다음 명령을 실행해 클러스터에 KEDA를 설치하세요:

    helm repo add kedacore https://kedacore.github.io/charts
helm upgrade --install keda kedacore/keda --namespace keda --create-namespace

    KEDA는 대기열 크기에 따라 배포 시스템을 자동으로 확장해요.

  3. 인그레스 구성: LangSmith 인스턴스용 인그레스, 게이트웨이 또는 Istio를 구성하세요. 모든 에이전트는 이 인그레스 뒤의 Kubernetes 서비스로 배포돼요. 인그레스 설정을 참고하세요. langsmith_config.yaml에 hostname을 제공해야 해요.

  4. 클러스터 용량 확인: 여러 배포를 위한 충분한 클러스터 용량이 있는지 확인하세요. 클러스터 오토스케일러를 권장해요.

  5. 스토리지 확인: 클러스터에 유효한 동적 PV 프로비저너 또는 PV가 있는지 확인하세요.

    kubectl get storageclass

    하나 이상의 StorageClass에 PROVISIONER 값(kubernetes.io/no-provisioner가 아닌)이 있고 (default)로 표시되어야 하거나, 진행하기 전에 하나를 구성해야 해요.

  6. egress 확인: https://beacon.langchain.com으로의 egress를 사용할 수 있는지 확인하세요. egress 문서를 참고하세요.

LangSmith Deployment 활성화

구성 요소

LangSmith Deployment를 활성화하면 클러스터에 다음 리소스가 프로비저닝돼요:

  • listener: 배포 변경을 위해 컨트롤 플레인을 듣고 다운스트림 CRD를 만들거나 업데이트해요.
  • LangGraphPlatform CRD: LangSmith Deployment 인스턴스를 관리해요.
  • operator: LangSmith CRD 변경을 처리해요.
  • host-backend: 컨트롤 플레인.

기능 활성화

LangSmith Deployment를 활성화하려면 langsmith_config.yaml을 업데이트하세요:

  1. 구성에서 deployment 활성화: langsmith_config.yaml에서 deployment 옵션을 활성화하세요. 유효한 인그레스도 구성되어 있어야 해요.

    config:
  deployment:
    enabled: true

    v0.12.0부터 langgraphPlatform 옵션은 더 이상 사용되지 않아요. v0.12.0 이후 버전에서는 config.deployment를 사용하세요.

  2. (선택) 이미지 미러링 구성: 이미지를 프라이빗 레지스트리로 미러링해야 한다면 langsmith_config.yaml에서 hostBackendImage와 operatorImage 옵션을 구성하세요. 최신 LangSmith Helm 차트 릴리스에 지정된 이미지 태그를 사용하세요.

    hostBackendImage:
  repository: "docker.io/langchain/hosted-langserve-backend"
  pullPolicy: IfNotPresent
operatorImage:
  repository: "docker.io/langchain/langgraph-operator"
  pullPolicy: IfNotPresent

  3. (선택) 기본 에이전트 템플릿 구성: 오퍼레이터가 에이전트 Kubernetes 리소스를 만드는 방법을 커스터마이즈해야 한다면 values.yaml의 기본 에이전트 템플릿을 재정의하세요. 가장 흔한 사용 사례는 프라이빗 컨테이너 레지스트리 인증을 위한 imagePullSecrets 추가예요. 자세한 내용은 프라이빗 레지스트리 인증 구성을 참고하세요.

  4. 변경 사항 적용: 변경 사항을 적용하려면 다음 명령을 실행하세요. 이 명령은 이 가이드 전체에서 변경 사항을 적용하라는 요청을 받을 때마다 사용돼요. <version>과 <namespace>를 값으로 바꾸세요:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

    계속하기 전에 새 팟이 실행 중인지 확인하세요:

    kubectl get pods -n <namespace>

    이제 인스턴스가 배포를 만들 준비가 됐어요.

Fleet, Insights 및 Chat 활성화

Fleet에는 LangSmith Self-Hosted v0.13 이상이 필요해요. 아래 설명된 독립 실행형 배포 모델에는 v0.15 이상이 필요해요.

각 기능에는 Fernet 암호화 키가 필요해요. 단일 Helm 구성에서 세 기능을 모두 활성화할 수 있어요.

구성 요소

이러한 기능을 활성화하면 각 기능(Fleet, Insights, Chat)에 대해 클러스터에 다음 구성 요소가 프로비저닝돼요:

  • api-server: 기능의 요청을 처리하는 메인 API 서버.
  • queue: 백그라운드 작업 처리 큐.
  • postgres: 기능 데이터용 전용 PostgreSQL 인스턴스. 외부 PostgreSQL 인스턴스로 교체 가능.
  • redis: 기능의 캐싱 및 pub/sub용 전용 Redis 인스턴스. 외부 Redis 인스턴스로 교체 가능.

Fleet은 추가로 프로비저닝해요:

  • toolServer: 에이전트용 MCP 도구 실행 제공.
  • triggerServer: 웹훅 및 예약 트리거 처리.

차트 0.16.0부터 Insights는 langsmith-insights-engine에서 실행되는데, 이는 insights와 engine 그래프를 모두 서빙하는 결합 이미지이며 차트는 기본적으로 이를 사용해요. 이전 Insights 전용 이미지 langsmith-clio는 폐지됐어요.

값이 images.engineInsightsAgentImage.repository를 langsmith-clio로 고정했다면 업그레이드 전에 해당 핀을 제거하거나 업데이트하세요. 차트가 이를 거부해요. 이미지를 프라이빗 레지스트리로 미러링한다면 langsmith-insights-engine을 미러링하고 저장소를 사본으로 가리키세요. 이미지 미러링을 참고하세요.

암호화 키 생성

각 기능은 자격 증명과 토큰 같은 기능별 시크릿을 암호화하기 위해 자체 Fernet 암호화 키를 사용해요. 키를 분리하면 독립적인 교체가 가능하고 키가 손상돼도 노출이 제한돼요. Python을 사용해 기능마다 키 하나를 생성하세요:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

각 키를 구성 파일에 직접 설정하는 대신 미리 정의된 Kubernetes 시크릿에 저장하는 것을 권장해요. 관련 파라미터는 기존 시크릿 사용을 참고하세요: agent_builder_encryption_key, insights_encryption_key, polly_encryption_key.

기능 활성화

  1. langsmith_config.yaml에 구성 추가:

    Kubernetes 시크릿 사용 (권장):

    config:
  existingSecretName: "<your-secret-name>"

fleet:
  enabled: true

insights:
  enabled: true

# Chat (formerly Polly)
polly:
  enabled: true

fleetToolServer:
  enabled: true

fleetTriggerServer:
  enabled: true

    이 이름으로 기존 시크릿을 참조해요. 차트는 agent_builder_encryption_key, insights_encryption_key, polly_encryption_key를 자동으로 읽어요.

    인라인 값 사용:

    fleet:
  enabled: true
  encryptionKey: "<fleet-encryption-key>"

insights:
  enabled: true
  encryptionKey: "<insights-encryption-key>"

polly:
  enabled: true
  encryptionKey: "<chat-encryption-key>"

fleetToolServer:
  enabled: true

fleetTriggerServer:
  enabled: true

    구성 파일에 암호화 키를 직접 설정해요. 이 파일을 버전 관리에 커밋하지 마세요.

    레거시 agentBootstrap 배포 모델에서 마이그레이션하는 경우 backend.agentBootstrap와 이전 config.agentBuilder, config.insights, config.polly 플래그를 비활성화하세요. 이것들은 위에 표시된 최상위 fleet, insights, polly 플래그가 아니라 config 섹션 아래의 플래그예요.

    또한 LangSmith Deployments UI를 통해 기존 Fleet, Insights 및 Chat 배포를 수동으로 삭제해야 해요. 레거시 agentBootstrap 모델에서 Fleet에 외부 PostgreSQL 데이터베이스를 사용하지 않았고 기존 Fleet 에이전트를 보존하려면, 이 구성을 적용하기 전에 지원 포털을 통해 기술 지원에 문의하세요.

    fleetToolServer와 fleetTriggerServer는 Fleet에 필요해요. 이것들은 Helm 차트 v15부터 폐지된 agentBuilderToolServer 및 agentBuilderTriggerServer 키를 대체했어요.

    각 기능은 기본적으로 자체 전용 PostgreSQL 및 Redis 인스턴스를 배포해요. 대신 외부 데이터베이스를 사용하려면 각 기능 아래의 postgres.external 및 redis.external 섹션을 구성하세요. 예:

    fleet:
  enabled: true
  encryptionKey: "<fleet-encryption-key>"
  postgres:
    external:
      enabled: true
      connectionUrl: "<fleet-postgres-connection-url>"
  redis:
    external:
      enabled: true
      connectionUrl: "<fleet-redis-connection-url>"

  2. 변경 사항 적용:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

    Fleet, Insights 및 Chat 팟이 실행 중인지 확인하세요:

    kubectl get pods -n <namespace>

(선택) Fleet용 OAuth 도구 및 트리거 활성화

Fleet에서 Gmail, Slack, Linear 같은 OAuth 기반 도구를 활성화하려면 providerOrgId를 구성하고 사용하려는 각 통합에 프로바이더 ID를 추가하세요. 원하는 프로바이더 조합을 활성화할 수 있어요.

사용 가능한 프로바이더

프로바이더 활성화되는 도구 활성화되는 트리거
googleOAuthProvider
설정 가이드		 Gmail, Google Calendar,
Google Sheets, BigQuery		 Gmail
linearOAuthProvider
설정 가이드		 Linear -
linkedinOAuthProvider
설정 가이드		 LinkedIn -
microsoftOAuthProvider
설정 가이드		 Outlook, Calendar, Teams, SharePoint,
Word, Excel, PowerPoint		 Outlook
salesforceOAuthProvider
설정 가이드		 Salesforce -
slackOAuthProvider
설정 가이드		 Slack Slack

일반 구성

다음을 langsmith_config.yaml에 추가하세요. 필요한 프로바이더만 포함하세요.

fleet:
  oauth:
    # Organization ID where OAuth providers are configured
    providerOrgId: "<your-org-id>"
    # Add provider IDs for integrations you want to enable.
    slackOAuthProvider: "<provider-id>"
    googleOAuthProvider: "<provider-id>"
    linkedinOAuthProvider: "<provider-id>"
    linearOAuthProvider: "<provider-id>"
    microsoftOAuthProvider: "<provider-id>"
    salesforceOAuthProvider: "<provider-id>"

프로바이더 ID는 고유해야 하며 -agent-builder 또는 -oauth-provider로 끝날 수 없어요.

프로바이더 설정 가이드

Google OAuth 프로바이더: Fleet에 Google OAuth를 활성화하려면 GCP에서 OAuth 클라이언트를 만들고 필수 URL과 자격 증명으로 구성하세요.

  1. GCP에서 OAuth 클라이언트 만들기: Google Cloud Console에서 새 OAuth 클라이언트 앱(Web application)을 만드세요.

  2. GCP에 URL 추가: OAuth 클라이언트에 다음 URL을 추가하고, <hostname>을 LangSmith 호스트 이름으로, <provider-id>를 사용할 프로바이더 ID(예: google)로 바꾸세요: Authorized JavaScript origins:

    • https://<hostname> Authorized redirect URIs:
    • https://<hostname>/api-host/v2/auth/callback/<provider-id>
    • https://<hostname>/host-oauth-callback/<provider-id>

  3. 자격 증명 복사: GCP OAuth 앱에서 Client ID와 Client Secret을 복사하세요.

  4. LangSmith에서 OAuth 프로바이더 구성: LangSmith에서 Settings > OAuth Providers로 가서 새 프로바이더를 추가하세요:

    • Client ID: GCP에서
    • Client Secret: GCP에서
    • Authorization URL: https://accounts.google.com/o/oauth2/auth
    • Token URL: https://oauth2.googleapis.com/token
    • Provider ID: 고유 문자열, 예: google

  5. 변경 사항 적용: LangSmith OAuth 프로바이더 ID를 langsmith_config.yaml에 추가하고 배포하세요:

    fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    googleOAuthProvider: "<provider-id>"

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Microsoft OAuth 프로바이더: Fleet에 Microsoft OAuth를 활성화하려면 Azure 앱 등록을 만들고, 필요한 Microsoft Graph 위임 권한을 추가하고, LangSmith에서 Microsoft OAuth 프로바이더를 구성하세요.

  1. Azure 앱 등록 만들기: Microsoft Entra 관리 센터에서 Applications > App registrations로 가서 새 등록을 만드세요.

  2. 지원 계정 유형 선택: 배포와 일치하는 계정 유형을 선택하세요. 여러 Microsoft Entra 테넌트의 사용자가 인증해야 하면 다중 테넌트 옵션을 선택하세요. 배포가 한 테넌트로 제한되면 단일 테넌트 앱 등록을 사용할 수 있어요.

  3. 리다이렉트 URI 추가: 다음 웹 리다이렉트 URI를 추가하고, <hostname>을 LangSmith 호스트 이름으로, <provider-id>를 프로바이더 ID로 바꾸세요:

    https://<hostname>/host-oauth-callback/<provider-id>

  4. 클라이언트 시크릿 만들기: Certificates & secrets에서 새 클라이언트 시크릿을 만드세요. Application (client) ID와 생성된 클라이언트 시크릿 값을 복사하세요.

  5. Microsoft Graph 위임 권한 추가: API permissions에서 다음 Microsoft Graph 위임 권한을 추가하세요:

    • Mail.ReadWrite
    • Mail.Send
    • Calendars.ReadWrite
    • Team.ReadBasic.All
    • Channel.ReadBasic.All
    • Channel.Create
    • ChannelMessage.Send
    • ChannelMessage.Read.All
    • Chat.Create
    • Chat.ReadWrite
    • User.ReadBasic.All
    • Files.ReadWrite.All
    • Sites.ReadWrite.All

    LangSmith는 Microsoft 프로바이더에 대해 offline_access를 자동으로 요청해서 사용자가 새로고침 토큰을 받을 수 있게 해요.

  6. 테넌트 동의 부여: Microsoft 365 정책이 이러한 위임 권한을 요구한다면 테넌트에 대해 관리자 동의를 부여하세요.

  7. LangSmith에서 OAuth 프로바이더 구성: Settings > OAuth Providers에서 새 프로바이더를 추가하세요:

    • Name: 예: Microsoft
    • Provider ID: 고유 문자열, 예: microsoft-oauth-provider
    • Client ID: Azure의 Application (client) ID
    • Client Secret: Azure의 클라이언트 시크릿 값
    • Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
    • Token URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
    • Provider Type: microsoft
    • Token endpoint auth method: client_secret_post

    단일 테넌트 앱 등록을 만들었다면 인증 및 토큰 URL의 common을 테넌트 ID로 바꾸세요.

  8. 변경 사항 적용: 다음을 langsmith_config.yaml에 추가하고 배포하세요:

    fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    microsoftOAuthProvider: "<provider-id>"

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Linear OAuth 프로바이더: Fleet에 Linear OAuth를 활성화하려면 Linear OAuth 앱을 만들고 필수 자격 증명으로 구성하세요.

  1. Linear OAuth 앱 만들기: Linear Settings > API > Applications로 가서 새 OAuth 애플리케이션을 만드세요.

  2. 콜백 URL 추가: 콜백 URL을 설정하고, <hostname>을 LangSmith 호스트 이름으로, <provider-id>를 프로바이더 ID로 바꾸세요:

    https://<hostname>/host-oauth-callback/<provider-id>

  3. 자격 증명 복사: 앱을 만든 후 Client ID와 Client Secret을 복사하세요.

  4. LangSmith에서 OAuth 프로바이더 구성: Settings > OAuth Providers에서 새 프로바이더를 추가하세요:

    • Client ID: Linear 앱에서
    • Client Secret: Linear 앱에서
    • Authorization URL: https://linear.app/oauth/authorize
    • Token URL: https://api.linear.app/oauth/token
    • Provider ID: 고유 문자열, 예: linear

  5. 변경 사항 적용: 다음을 langsmith_config.yaml에 추가하고 배포하세요:

    fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    linearOAuthProvider: "<provider-id>"

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

LinkedIn OAuth 프로바이더: Fleet에 LinkedIn OAuth를 활성화하려면 LinkedIn OAuth 앱을 만들고 필수 자격 증명으로 구성하세요.

  1. LinkedIn OAuth 앱 만들기: linkedin.com/developers/apps로 가서 새 앱을 만드세요.

  2. 리다이렉트 URI 추가: 앱 설정에서 Auth 탭으로 가세요. 다음 리다이렉트 URI를 추가하고, <hostname>을 LangSmith 호스트 이름으로, <provider-id>를 프로바이더 ID로 바꾸세요:

    https://<hostname>/host-oauth-callback/<provider-id>

  3. 자격 증명 복사: Auth 탭에서 Client ID와 Client Secret을 복사하세요.

  4. LangSmith에서 OAuth 프로바이더 구성: Settings > OAuth Providers에서 새 프로바이더를 추가하세요:

    • Client ID: LinkedIn 앱에서
    • Client Secret: LinkedIn 앱에서
    • Authorization URL: https://www.linkedin.com/oauth/v2/authorization
    • Token URL: https://www.linkedin.com/oauth/v2/accessToken
    • Provider ID: 고유 문자열, 예: linkedin

  5. 변경 사항 적용: 다음을 langsmith_config.yaml에 추가하고 배포하세요:

    fleet:
  oauth:
    providerOrgId: "<your-org-id>"
    linkedinOAuthProvider: "<provider-id>"

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Salesforce OAuth 프로바이더: Fleet에 Salesforce OAuth를 활성화하려면 Salesforce External Client App을 만들고, OAuth 설정과 정책을 구성하고, 자격 증명을 검색한 다음 LangSmith에서 Salesforce OAuth 프로바이더를 구성하세요.

  1. External Client App 만들기: Salesforce Setup에서 Quick Find로 External Client App Manager를 열고 New External Client App을 클릭하세요. Basic Information 아래에서:

    • External Client App Name: 예: LangSmith Fleet
    • Contact Email: 관리자 이메일 주소
    • Distribution State: Local

    External Client Apps는 Salesforce가 OAuth 통합에 사용하는 현재 프레임워크예요. New External Client App을 사용할 수 없으면 Setup > External Client App Settings 아래에서 앱 생성이 조직에 활성화돼 있는지 확인하세요.

  2. OAuth 활성화 및 OAuth 설정 구성: **API (Enable OAuth Settings)**를 펼치고 Enable OAuth를 선택하세요. 그런 다음 구성하세요:

    • Callback URL, <hostname>을 LangSmith 호스트 이름으로, <provider-id>를 프로바이더 ID로 바꾸기:

      https://<hostname>/host-oauth-callback/<provider-id>

    • Selected OAuth Scopes: Manage user data via APIs (api) 및 Perform requests at any time (refresh_token, offline_access) 추가.

    • Require Secret for the Web Server Flow 선택 유지.

    • Enable Authorization Code and Credentials Flow 및 Enable Client Credentials Flow는 선택하지 않음. Fleet은 표준 웹 서버(인증 코드) 흐름을 사용해요.

    Create를 클릭하세요.

  3. OAuth 정책 설정: 앱을 열고 Policies 탭을 선택한 다음 Edit을 클릭하세요:

    • Refresh Token Policy: Refresh token is valid until revoked 선택.
    • Permitted Users: All users may self-authorize 유지. 대신 Admin approved users are pre-authorized를 선택하면 먼저 권한 세트나 프로필에 앱을 할당해야 해요. 그렇지 않으면 인증이 실패해요.

    Save를 클릭하세요.

    External Client App은 두 곳에서 구성돼요: Settings(이전 단계의 OAuth 정의)와 Policies(이 단계). 둘 다 저장해야 해요.

  4. 자격 증명 복사: Settings 탭의 OAuth Settings 아래에서 Consumer Key and Secret을 선택하세요. Consumer Key가 Client ID이고 Consumer Secret이 Client Secret이에요.

    앱을 만든 후 첫 연결 시도 전에 전파되도록 최대 30분을 기다리세요.

  5. LangSmith에서 OAuth 프로바이더 구성: Settings > OAuth Providers에서 OAuth Provider를 클릭하고 채우세요:

    • Provider ID: 고유 문자열, 예: salesforce-oauth-provider. 다음 단계의 salesforceOAuthProvider에 같은 값을 사용하세요.
    • Display Name: 예: Salesforce
    • Client ID: Salesforce의 Consumer Key
    • Client Secret: Salesforce의 Consumer Secret
    • Authorization URL: https://<MyDomain>.my.salesforce.com/services/oauth2/authorize
    • Token URL: https://<MyDomain>.my.salesforce.com/services/oauth2/token

    LangSmith는 Token URL에서 Salesforce를 자동으로 인식하므로 설정할 프로바이더 유형이나 토큰 인증 방법 필드가 없어요. 위에서 구성한 웹 서버 흐름과 일치하도록 Enable PKCE를 끄세요.

    <MyDomain>을 조직의 My Domain으로 바꾸세요. Setup > My Domain에서 찾을 수 있어요. 샌드박스의 경우 https://<MyDomain>--<SandboxName>.sandbox.my.salesforce.com/services/oauth2/authorize와 일치하는 토큰 URL을 사용하세요.

  6. 변경 사항 적용: 다음을 langsmith_config.yaml에 추가하고 배포하세요:

    fleet:
  oauth:
    providerOrgId: "<your-langsmith-org-id>"
    salesforceOAuthProvider: "<provider-id>"

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

    로그인이 실패하면: Salesforce의 Callback URL이 https://<hostname>/host-oauth-callback/<provider-id>와 정확히 일치하는지(HTTPS, 후행 슬래시 없음) 확인하고, Admin approved users are pre-authorized를 선택했다면 권한 세트를 통해 앱을 할당하고, 조직이 로그인 IP 범위를 적용한다면 Fleet 서버의 egress IP를 사용자 프로필에 허용 목록에 추가하거나 앱 정책에서 IP Relaxation을 Relax IP restrictions로 설정하세요.

Slack OAuth 프로바이더: 하나의 Slack OAuth 프로바이더가 Slack 도구와 개별 에이전트에 추가하는 Slack 앱을 모두 지원하므로, Slack 설정은 나머지 Slack 통합과 함께 있어요.

전체 워크스루는 셀프 호스팅에서 Slack 설정을 참고하세요. Slack 앱 만들기, 봇 스코프 추가, 프로바이더 등록, 리다이렉트 URI 설정, Helm 값 구성을 다뤄요.

(선택) Fleet용 GitHub App 활성화

Fleet은 전용 GitHub App(OAuth 앱이 아님)을 통해 GitHub와 통합해요. GitHub App은 Fleet의 GitHub 도구에 저장소 접근을 제공하고 개인 저장소 접근에 필요한 사용자 인증 흐름을 지원해요.

설정은 GitHub App 만들기, 자격 증명 수집, Kubernetes 시크릿으로 저장, langsmith_config.yaml에서 참조하는 것으로 구성돼요.

  1. GitHub App 만들기: GitHub Settings > Developer settings > GitHub Apps로 가서 New GitHub App을 클릭하세요.

    개인 계정이나 조직에서 앱을 만들 수 있어요. 여러 사람이 통합을 관리한다면 조직 소유 앱을 권장해요.

  2. 기본 정보 채우기:

    • GitHub App name: 고유한 이름, 예: acme-langsmith-fleet. GitHub가 생성하는 슬러그(이름의 소문자, 하이픈 형태)를 기록해 두세요. FLEET_GITHUB_APP_SLUG에 사용할 값이에요.
    • Homepage URL: LangSmith 호스트 이름, 예: https://langsmith.acme.com.
    • 지금은 Webhook 아래의 Active를 선택 해제하세요. 이후 단계에서 웹훅 시크릿을 생성한 후 활성화할 거예요.

  3. 콜백 URL 설정: Identifying and authorizing users 아래에서 다음 Callback URL을 추가하고, <hostname>을 LangSmith 호스트 이름으로 바꾸세요:

    https://<hostname>/api/v1/platform/fleet/providers/github-app/auth/callback

    Redirect on update를 선택하세요. Post installation 아래에서 다음 Setup URL을 추가하세요:

    https://<hostname>/api/v1/platform/fleet/providers/github-app/callback

    Redirect on update를 선택하세요.

  4. 웹훅 URL 설정 및 웹훅 시크릿 생성: 무작위 웹훅 시크릿을 생성하세요:

    python3 -c "import secrets; print(secrets.token_urlsafe(48))"

    Webhook 아래에서:

    • Active를 선택하세요.

    • Webhook URL을 다음으로 설정하세요:

      https://<hostname>/api/v1/platform/fleet/providers/github-app/webhooks

    • 생성된 값을 Webhook secret에 붙여 넣으세요. 이후 단계에서 Kubernetes 시크릿을 만들 때 같은 값이 필요하므로 저장하세요.

  5. 저장소 권한 설정: Permissions > Repository permissions 아래에서 다음을 부여하세요:

    • Contents: 읽기 및 쓰기
    • Issues: 읽기 및 쓰기
    • Pull requests: 읽기 및 쓰기
    • Metadata: 읽기 전용 (자동 선택됨)

    Permissions > Account permissions 아래에서 Email addresses: Read-only를 부여하세요.

    이것들은 Fleet의 내장 GitHub 도구(이슈 관리, 풀 리퀘스트 생성, 저장소 콘텐츠 접근)에 필요한 최소 권한이에요. 추가 도구 기능이 필요하면 조정하세요.

  6. 설치 가시성 선택: Where can this GitHub App be installed? 아래에서 배포 요구 사항과 일치하는 옵션을 선택하세요. 대부분의 셀프 호스팅 배포에서는 Only on this account가 맞아요.

  7. 앱 만들기: Create GitHub App을 클릭하세요. 앱 설정 페이지에서 다음 값을 기록하세요:

    값 어디서 찾을까 환경 변수
    App ID 숫자, 페이지 상단 FLEET_GITHUB_APP_ID
    Public link 예: https://github.com/apps/acme-langsmith-fleet FLEET_GITHUB_APP_PUBLIC_LINK
    App slug 공개 링크의 마지막 경로 세그먼트 FLEET_GITHUB_APP_SLUG
    Client ID About 아래 FLEET_GITHUB_APP_CLIENT_ID

  8. 클라이언트 시크릿 생성: Client secrets 아래에서 Generate a new client secret을 클릭하고 값을 복사하세요. 이것은 FLEET_GITHUB_APP_CLIENT_SECRET이에요. GitHub는 한 번만 보여줘요.

  9. 개인 키 생성: Private keys로 스크롤하고 Generate a private key를 클릭하세요. GitHub가 .pem 파일을 다운로드해요. 전체 GitHub App 접근을 부여하므로 이 파일을 안전하게 보관하세요. PEM 내용은 FLEET_GITHUB_APP_PRIVATE_KEY예요.

  10. 상태 JWT 시크릿 생성: LangSmith는 HMAC 키로 단기 OAuth 상태 토큰에 서명해요. 하나 생성하세요:

    python3 -c "import secrets; print(secrets.token_urlsafe(48))"

    이것은 FLEET_GITHUB_APP_STATE_JWT_SECRET이에요.

  11. Kubernetes 시크릿 만들기: 민감한 값을 Kubernetes 시크릿에 저장하세요:

    kubectl create secret generic fleet-github-app \
  --namespace <your-langsmith-namespace> \
  --from-literal=client_secret="<client-secret>" \
  --from-literal=webhook_secret="<webhook-secret>" \
  --from-literal=state_jwt_secret="<state-jwt-secret>" \
  --from-file=private_key=/path/to/fleet-app.private-key.pem

    프로덕션 배포에서는 기존 시크릿 워크플로(예: Sealed Secrets 또는 External Secrets Operator)를 통해 이 시크릿을 관리하세요. 자세한 내용은 기존 시크릿 사용을 참고하세요.

  12. langsmith_config.yaml에 구성 추가: 위에서 수집한 비민감 값으로 자리 표시자를 바꿔 다음을 추가하세요:

    commonEnv:
  - name: FLEET_GITHUB_APP_ID
    value: "<app-id>"
  - name: FLEET_GITHUB_APP_SLUG
    value: "<app-slug>"
  - name: FLEET_GITHUB_APP_PUBLIC_LINK
    value: "https://github.com/apps/<app-slug>"
  - name: FLEET_GITHUB_APP_CLIENT_ID
    value: "<client-id>"
  - name: FLEET_GITHUB_APP_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: client_secret
  - name: FLEET_GITHUB_APP_PRIVATE_KEY
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: private_key
  - name: FLEET_GITHUB_APP_WEBHOOK_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: webhook_secret
  - name: FLEET_GITHUB_APP_STATE_JWT_SECRET
    valueFrom:
      secretKeyRef:
        name: fleet-github-app
        key: state_jwt_secret

fleetToolServer:
  deployment:
    extraEnv:
      - name: FLEET_GITHUB_APP_ENABLED
        value: "true"

    FLEET_GITHUB_APP_ENABLED은 GitHub 도구가 등록되도록 도구 서버에 설정해야 해요. 나머지 FLEET_GITHUB_APP_* 변수는 플랫폼 백엔드가 소비하며 commonEnv 아래에 있어요.

  13. 배포 및 저장소에 앱 설치: 변경 사항을 적용하려면 다음 명령을 실행하세요:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

    팟이 정상이 되면:

    1. LangSmith에서 Fleet 에이전트를 열고 에이전트 편집기의 GitHub 통합으로 가세요.
    2. Connect GitHub를 클릭해 Fleet이 접근해야 할 저장소에 앱을 설치하세요.
    3. 개인 저장소의 경우 설치 중에 각 저장소를 명시적으로 선택해야 해요.

    각 사용자는 LangSmith의 재인증 흐름을 사용해 자체 GitHub 계정에 대해 GitHub App을 승인해야 해요. 이렇게 하면 Fleet이 사용자를 대신해 행동하는 도구의 사용자별 토큰을 해석할 수 있어요.

기능 비활성화

Fleet, Insights 및 Chat의 어떤 조합이든 비활성화하려면 langsmith_config.yaml에서 해당 플래그를 false로 설정하세요:

fleet:
  enabled: false

insights:
  enabled: false

polly:
  enabled: false

Sandboxes 활성화

Azure의 셀프 호스팅 Sandboxes에는 LangSmith Helm 차트 v17(0.17.x)이 필요해요.

Sandboxes는 기본적으로 비활성화돼 있어요. 설치 후 LangSmith UI의 사용자 워크플로와 API는 LangSmith Sandboxes를 참고하세요.

지원되는 플랫폼

셀프 호스팅 Sandboxes는 다음에서 지원돼요:

  • Amazon Elastic Kubernetes Service (EKS)
  • Google Kubernetes Engine (GKE)
  • Azure Kubernetes Service (AKS)

구성 요소

Sandboxes를 활성화하면 다음 리소스가 프로비저닝돼요:

  • KVM 지원 노드에서 샌드박스 워크로드를 실행하는 샌드박스 런타임 팟.
  • Redis로 백업되는 JuiceFS 메타데이터 스토어와 S3, GCS 또는 Azure Blob Storage로 백업되는 객체 스토리지.
  • Sandboxes 내부에서 노출되는 서비스용 선택적 와일드카드 인그레스.

사전 요구 사항

  1. 기본 LangSmith 플랫폼 설치: Sandboxes를 활성화하기 전에 Kubernetes에 LangSmith를 설치하세요. Kubernetes에서 LangSmith 셀프 호스팅을 참고하세요.

    Sandboxes는 LangSmith 릴리스와 같은 Kubernetes 클러스터 및 네임스페이스에서 실행돼요.

  2. KVM 지원 노드 추가: 클러스터에는 /dev/kvm에서 Linux KVM을 사용할 수 있는 중첩 워크로드를 실행할 수 있는 전용 노드가 포함되어야 해요.

    이것들은 중첩 가상화가 활성화된 베어메탈 머신이나 지원되는 클라우드 인스턴스일 수 있어요. AWS와 GCP에서는 샌드박스 런타임에 /dev/kvm을 노출하는 x86_64 Linux 인스턴스를 사용하세요.

    EKS에서 VPC CNI 애드온은 v1.21 이상이어야 해요. v1.20.0은 8세대 Intel 인스턴스(예: m8i)에서 충돌해요: aws-node가 CrashLoopBackOff 상태가 되고, 노드가 cni plugin not initialized를 보고하며, 관리형 노드 그룹은 결국 NodeCreationFailure: Unhealthy nodes in the kubernetes cluster로 실패해요.

    기본 Helm 스케줄링 값은 이 노드들에 다음 레이블과 테인트가 있을 것으로 기대해요:

    label:
  sandbox.langsmith.com/host: "true"
taint:
  key: sandbox.langsmith.com/host
  value: "true"
  effect: NoSchedule

    노드가 다른 레이블이나 테인트를 사용한다면 sandboxes.sandboxHost.deployment.nodeSelector와 sandboxes.sandboxHost.deployment.tolerations를 재정의하세요.

  3. JuiceFS 스토리지 구성: Sandboxes에는 JuiceFS 기반 공유 스토리지가 필요해요. 다음을 제공해야 해요:

    • Redis 호환 메타데이터 스토어.
    • 객체 스토리지 버킷 또는 버킷 루트.
    • JuiceFS 구성 Secret 또는 차트가 하나를 만들 충분한 Helm 값.

    sandboxes.juicefs.storage와 sandboxes.juicefs.bucket에 다음 객체 스토리지 백엔드를 사용하세요:

    플랫폼 Storage 값 버킷 형식
    AWS s3 지역 명시 HTTPS S3 엔드포인트, 예: https://bucket-name.s3.us-west-2.amazonaws.com
    GCP gs GCS URL, 예: gs://bucket-name
    Azure wasb Azure Blob Storage URL, 예: https://container-name.core.windows.net

    sandboxes.juicefs.name에 객체 스토어 하위 경로를 사용하지 마세요. sandbox-juicefs 같은 평면 이름을 사용하세요. JuiceFS는 구성된 버킷 안의 그 이름 아래에 객체를 저장해요.

    Redis 메타데이터 스토어의 경우 maxmemory-policy를 noeviction으로 설정하는 것을 권장해요. 이렇게 하면 메모리 압력 하에서 JuiceFS 메타데이터가 축출되는 것을 피할 수 있어요. Redis 용량을 모니터링하고 메모리 한도에 도달하기 전에 확장하세요.

    noeviction에서는 Redis가 최대 메모리에 도달하면 쓰기가 실패할 수 있으므로, 샌드박스 메타데이터 성장을 위한 충분한 메모리 여유를 유지하세요.

  4. 샌드박스 시크릿 구성: Sandboxes에는 서비스 간 인증과 콜백 서명을 위한 추가 시크릿 자료가 필요해요.

    Kubernetes 시크릿 사용 (권장):

    stringData:
  sandbox_callback_signing_jwk: '<ed25519-private-jwk>'

    config.existingSecretName을 사용한다면 같은 LangSmith 앱 Secret에 샌드박스 키를 추가하세요. Helm에서 시크릿 값을 직접 설정하지 마세요.

    인라인 값 사용:

    sandboxes:
  callbackSigningJwk: '<ed25519-private-jwk>'

    Helm 차트가 LangSmith 앱 Secret을 관리한다면 구성 파일에 샌드박스 시크릿 값을 직접 설정하세요. 이 파일을 버전 관리에 커밋하지 마세요.

    콜백 서명 값은 Ed25519 개인 JWK여야 해요. 업그레이드 간에 안정적으로 유지하세요.

  5. 프록시 CA 모드 선택: 샌드박스 egress 인증 프록시는 TLS 인터셉션과 자격 증명 주입에 이 CA를 사용해요.

    차트는 두 가지 프록시 CA 모드를 지원해요:

    모드 사용 시점
    generatedSecret Helm이 자체 서명 CA Secret을 만들기를 원할 때. 기본값.
    existingSecret LangSmith 차트 밖에서 CA Secret을 관리할 때. Secret은 수동, cert-manager 또는 다른 외부 프로세스로 만들 수 있어요.

    라이브 클러스터 접근 없이 매니페스트를 렌더링하는 GitOps 워크플로에서는 existingSecret을 선호하세요. generatedSecret 모드는 Helm의 라이브 lookup 동작을 사용해 업그레이드 시 생성된 Secret을 재사용하는데, 순수 렌더 워크플로는 라이브 Secret을 읽을 수 없어 렌더마다 새 인증서 자료를 만들 수 있어요.

Helm으로 활성화

사전 요구 사항에 설명된 샌드박스 시크릿 값과 함께 langsmith_config.yaml에 다음 값을 추가하세요. 배포별 값으로 자리 표시자를 바꾸세요.

AWS:

images:
  sandboxHostImage:
    tag: "<same-release-tag-as-your-langsmith-images>"

sandboxes:
  enabled: true
  juicefs:
    name: "sandbox-juicefs"
    storage: "s3"
    bucket: "https://bucket-name.s3.us-west-2.amazonaws.com"
    redis:
      metaURL: "redis://redis-host:6379/1"
  sandboxHost:
    deployment:
      nodeSelector:
        kubernetes.io/arch: "amd64"
        sandbox.langsmith.com/host: "true"
    serviceAccount:
      annotations:
        eks.amazonaws.com/role-arn: "<role_arn>"

GCP:

images:
  sandboxHostImage:
    tag: "<same-release-tag-as-your-langsmith-images>"

sandboxes:
  enabled: true
  juicefs:
    name: "sandbox-juicefs"
    storage: "gs"
    bucket: "gs://bucket-name"
    redis:
      metaURL: "redis://redis-host:6379/1"
  sandboxHost:
    deployment:
      nodeSelector:
        kubernetes.io/arch: "amd64"
        sandbox.langsmith.com/host: "true"
    serviceAccount:
      annotations:
        iam.gke.io/gcp-service-account: "<gsa_name>@<project_id>.iam.gserviceaccount.com"

Azure:

images:
  sandboxHostImage:
    tag: "<same-release-tag-as-your-langsmith-images>"

sandboxes:
  enabled: true
  juicefs:
    name: "sandbox-juicefs"
    storage: "wasb"
    bucket: "https://container-name.core.windows.net"
    storageAccountName: "<storage-account-name>"
    redis:
      metaURL: "redis://redis-host:6379/1"
  juicefsFormatJob:
    labels:
      azure.workload.identity/use: "true"
  sandboxHost:
    deployment:
      labels:
        azure.workload.identity/use: "true"
      nodeSelector:
        kubernetes.io/arch: "amd64"
        sandbox.langsmith.com/host: "true"
    serviceAccount:
      annotations:
        azure.workload.identity/client-id: "<client_id>"

업데이트된 차트를 적용하세요:

helm upgrade -i langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace> \
  --wait

Terraform으로 활성화

LangSmith Terraform 모듈은 필요한 AWS 및 GCP 인프라를 프로비저닝하고 해당 Helm 값을 생성할 수 있어요.

AWS: modules/aws/infra/terraform.tfvars에서 Sandboxes를 활성화하고 샌드박스 노드 용량을 구성하세요:

enable_sandboxes = true
redis_source     = "external"

sandbox_juicefs_redis_instance_type             = "cache.m6g.large"
sandbox_juicefs_redis_snapshot_retention_limit  = 7

sandbox_host_node_count               = 1
sandbox_host_instance_types           = ["m5d.metal"]
sandbox_host_configure_instance_store = true

sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

AWS Sandboxes에는 redis_source = "external"이 필요해요. Terraform 모듈은:

  • JuiceFS 샌드박스 메타데이터용 전용 ElastiCache Redis 인스턴스를 만들어요.
  • 그 전용 인스턴스를 권장 noeviction 정책으로 구성해요.
  • 샌드박스 객체 스토리지에 LangSmith S3 버킷을 재사용해요.
  • JuiceFS 구성 Secret을 만들어요.
  • 예상 노드 레이블과 테인트를 추가해요.

AWS 설정 스크립트는 일반 SSM 기반 설정 흐름을 통해 샌드박스 서비스 인증 시크릿, 콜백 서명 JWK, 전용 JuiceFS Redis 인증 토큰을 생성해요. 이러한 값이 아직 없으면 Terraform을 적용하기 전에 infra 설정 스크립트를 실행하세요.

Terraform 앱 모듈로 Helm 릴리스를 배포한다면 modules/aws/app/terraform.tfvars에도 샌드박스 앱 값을 설정하세요:

enable_sandboxes      = true
chart_version          = "~0.17.0"
sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

enable_sandboxes = true일 때 Terraform 앱 모듈은 명시적 LangSmith Helm 차트 v17 릴리스와 샌드박스 런타임 이미지 태그를 요구해요.

일반 AWS 흐름을 실행하세요:

make apply
make init-values
CHART_VERSION="~0.17.0" make deploy

GCP: modules/gcp/infra/terraform.tfvars에서 Sandboxes를 활성화하고 Standard GKE 노드 풀을 구성하세요:

enable_sandboxes = true
redis_source     = "external"

gke_use_autopilot     = false
enable_gcp_iam_module = true

sandbox_juicefs_redis_memory_size       = 5
sandbox_juicefs_redis_high_availability = true

sandbox_host_node_count     = 1
sandbox_host_min_node_count = 1
sandbox_host_max_node_count = 5
sandbox_host_machine_type   = "n2-standard-8"

sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

GCP Sandboxes에는 redis_source = "external"이 필요해요. Terraform 모듈은:

  • JuiceFS 샌드박스 메타데이터용 전용 Memorystore Redis 인스턴스를 만들어요.
  • 그 전용 인스턴스를 권장 noeviction 정책으로 구성해요.
  • 샌드박스 객체 스토리지에 LangSmith GCS 버킷을 재사용해요.
  • JuiceFS 구성 Secret을 만들어요.
  • 예상 노드 레이블과 테인트를 추가해요.

GCP 설정 스크립트는 일반 Secret Manager 설정 흐름을 통해 샌드박스 서비스 인증 시크릿과 콜백 서명 JWK를 생성해요. 이러한 값이 아직 없으면 Terraform을 적용하기 전에 infra 설정 스크립트를 실행하세요.

Terraform 앱 모듈로 Helm 릴리스를 배포한다면 modules/gcp/app/terraform.tfvars에도 샌드박스 앱 값을 설정하세요:

enable_sandboxes      = true
chart_version          = "~0.17.0"
sandbox_host_image_tag = "<same-release-tag-as-your-langsmith-images>"

enable_sandboxes = true일 때 Terraform 앱 모듈은 명시적 LangSmith Helm 차트 v17 릴리스와 샌드박스 런타임 이미지 태그를 요구해요.

일반 GCP 흐름을 실행하세요:

make apply
make init-values
CHART_VERSION="~0.17.0" make deploy

선택: 서비스 URL 활성화

사용자가 Sandboxes 내부에서 실행되는 HTTP 서비스에 브라우저 또는 프로그래밍 방식으로 접근해야 할 때 sandboxes.serviceUrlBaseUrl을 설정하세요.

sandboxes:
  serviceUrlBaseUrl: "https://sandbox-services.example.com"

이것은 *.sandbox-services.example.com에 대한 와일드카드 DNS와 TLS가 필요해요. ingress.enabled가 true이면 차트는 이러한 서비스 URL을 LangSmith 플랫폼 백엔드로 라우팅하는 와일드카드 인그레스 규칙도 추가해요.

설치 검증

업그레이드가 완료된 후 샌드박스 런타임 팟과 JuiceFS 볼륨이 준비됐는지 확인하세요:

kubectl rollout status deployment/sandbox-host -n <namespace>
kubectl get pods,pvc -n <namespace>

그런 다음 샌드박스 스모크 테스트를 실행하세요:

  1. Python 이미지 같은 공개 이미지에서 샌드박스를 만드세요.
  2. 샌드박스 안에서 Python HTTP 서버를 시작하세요.
  3. 메모리를 활성화해 샌드박스를 스냅샷하세요.
  4. 스냅샷에서 새 샌드박스를 만드세요.
  5. 복원된 샌드박스에서 HTTP 서버가 여전히 실행 중인지 확인하세요.

업그레이드 노트

샌드박스 런타임 이미지 변경은 sandbox-host Kubernetes Deployment를 통해 롤아웃돼요. 차트는 기본적으로 무서지(no-surge) 롤링 업데이트 전략을 사용하므로 호스트가 한 번에 하나씩 교체돼요.

일반 Helm 업그레이드 중 종료 중인 호스트는 새 Sandboxes 수락을 중지하고, 실행 중인 각 Sandbox의 VM 메모리를 JuiceFS에 저장하려 시도한 다음, 팟이 종료되기 전에 해당 VM을 중지해요. 이 종료는 기본 300초인 sandbox-host 팟 종료 유예 기간으로 제한돼요. 이것은 라이브 마이그레이션이 아니에요. 해당 호스트의 Sandboxes는 재시작 중 중단돼요.

Sandboxes는 사전에 재시작되지 않아요. 사용자나 API 동작이 Sandbox를 시작하거나 요청 경로가 깨울 때 다시 시작돼요. 그러면 LangSmith가 Sandbox를 사용 가능한 호스트에 배치하고, 종료 캡처가 완료됐다면 저장된 메모리 이미지에서 복원해요. 메모리 이미지가 없거나 불완전하면 Sandbox는 저장된 루트 파일시스템에서 시작돼요.

Engine 활성화

셀프 호스팅 배포에는 LangSmith Helm 차트 0.16.0 이상과 Engine 엔타이틀먼트를 포함하는 라이선스가 필요해요. Engine은 별도로 라이선스가 부여되고 자체 사용량을 LCU로 계량해요. 영업 팀에 문의해 주문에 추가하세요.

Engine은 프로덕션 트레이스를 보고, 반복되는 실패를 이슈로 클러스터링하고, 각 이슈를 진단하며, 수정 사항을 제안해요. Engine은 기본적으로 비활성화돼 있어요.

Engine은 Sandboxes를 필요로 하고, Insights도 활성화돼 있으면 Insights와 배포를 공유해요. 이 페이지의 다른 기능과 달리 Engine은 클러스터 안에서 완전히 실행될 수 없어요. 진단과 수정을 지원하는 모델 작업에 LangChain 관리형 기록 보존 없음 서비스인 LangSmith Intelligence를 사용하기 때문이에요.

그 이유로 Engine의 설치, egress, 데이터 처리는 한 페이지에 함께 문서화돼 있어요. 지역 가용성, 사전 요구 사항, Helm 값, 검증 단계는 셀프 호스팅의 Engine을 참고하세요.

선택적 구성

추가 데이터 플레인 구성

권장되지 않음; 폐기 예정. 컨트롤 플레인을 통한 추가 데이터 플레인 구성은 권장되지 않는 접근 방식이며 향후 릴리스에서 폐기될 거예요. 대신 독립 실행형 Agent Servers를 배포하고 셀프 호스팅 LangSmith 인스턴스로 추적하도록 구성하세요.

위에서 만든 데이터 플레인에 더해, 다른 Kubernetes 클러스터나 다른 네임스페이스 아래의 같은 클러스터에 더 많은 데이터 플레인을 만들 수 있어요. 이를 달성하는 여러 방법이 있으므로, 사용 사례에 가장 잘 맞는 솔루션을 구현하세요.

사전 요구 사항:

  1. 클러스터 조직 검토: 하이브리드(레거시) 문서의 클러스터 조직 가이드를 읽어 사용 사례에 맞게 구성하는 방법을 이해하세요.

  2. 하이브리드 사전 요구 사항 검증: 새 클러스터에 대한 하이브리드 섹션의 사전 요구 사항을 검증하세요. 사전 요구 사항의 5단계에서 https://api.host.langchain.com과 https://api.smith.langchain.com 대신 셀프 호스팅 LangSmith 인스턴스로 egress를 구성하세요.

  3. Postgres에서 기능 활성화: LangSmith Postgres 인스턴스에 대해 다음을 실행해 이 기능을 활성화하세요. 이후 단계를 위해 워크스페이스 ID를 기록하세요.

    update organizations set config = config || '{"enable_lgp_listeners_page": true}' where id = '<org id here>';
update tenants set config = config || '{"langgraph_remote_reconciler_enabled": true}' where id = '<workspace id here>';

다른 클러스터에 배포:

  1. 하이브리드 설정 가이드 따르기: 하이브리드 설정 가이드의 2~6단계를 따르세요. config.langsmithWorkspaceId를 이전 단계의 워크스페이스 ID로 설정하세요.
  2. (선택) 같은 클러스터에 데이터 플레인 더 추가: 같은 클러스터에 둘 이상의 데이터 플레인을 추가하려면 같은 클러스터에서 추가 데이터 플레인 구성 지침을 따르세요.

같은 클러스터의 다른 네임스페이스에 배포:

  1. 구성 업데이트: langsmith_config.yaml에서 다음 수정을 하세요:

    • operator.watchNamespaces를 셀프 호스팅 LangSmith 인스턴스가 실행 중인 현재 네임스페이스로 설정하세요. 이렇게 하면 새 데이터 플레인이 추가한 오퍼레이터와의 충돌을 방지해요.
    • Gateway API 또는 Istio Gateway를 사용하세요. 그에 따라 langsmith_config.yaml을 조정하세요.

  2. 변경 사항 적용:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

  3. 하이브리드 설정 가이드 따르기: 하이브리드 설정 가이드의 2~6단계를 따르세요. config.langsmithWorkspaceId를 이전 단계의 워크스페이스 ID로 설정하세요. config.watchNamespaces를 기존 데이터 플레인이 사용하는 것과 다른 네임스페이스로 설정하세요.

  4. (선택) 로그 접근 구성: 컨트롤 플레인이 새 네임스페이스의 Agent Server 배포 로그를 읽도록 접근을 구성하세요. 다른 네임스페이스의 Agent Server 로그 읽기를 참고하세요.

프라이빗 레지스트리 인증 구성

Agent Server 배포가 프라이빗 컨테이너 레지스트리(예: AWS ECR, Azure ACR 또는 GCP Artifact Registry)의 이미지를 사용한다면 이미지 풀 시크릿을 구성하세요. 이 구성은 모든 배포에 자동으로 적용되어 프라이빗 레지스트리로 인증할 수 있게 해요.

  1. Kubernetes 이미지 풀 시크릿 만들기:

    kubectl create secret docker-registry langsmith-registry-secret \
    --docker-server=myregistry.com \
    --docker-username=your-username \
    --docker-password=your-password \
    [email protected] \
    -n langsmith

    값을 레지스트리 자격 증명으로 바꾸세요:

    • myregistry.com: 레지스트리 URL
    • your-username: 레지스트리 사용자 이름
    • your-password: 레지스트리 비밀번호 또는 접근 토큰
    • langsmith: LangSmith가 설치된 Kubernetes 네임스페이스

  2. langsmith_config.yaml에서 배포 템플릿 구성: 에이전트 서버 배포가 프라이빗 레지스트리 시크릿을 사용하도록 오퍼레이터의 배포 템플릿에 imagePullSecrets를 추가하세요:

    operator:
  templates:
    deployment: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ${name}
        namespace: ${namespace}
      spec:
        replicas: ${replicas}
        revisionHistoryLimit: 10
        selector:
          matchLabels:
            app: ${name}
        template:
          metadata:
            labels:
              app: ${name}
          spec:
            enableServiceLinks: false
            imagePullSecrets:
            - name: langsmith-registry-secret
            containers:
            - name: api-server
              image: ${image}
              ports:
              - name: api-server
                containerPort: 8000
                protocol: TCP
              livenessProbe:
                httpGet:
                  path: /ok
                  port: 8000
                periodSeconds: 15
                timeoutSeconds: 5
                failureThreshold: 6
              readinessProbe:
                httpGet:
                  path: /ok
                  port: 8000
                periodSeconds: 15
                timeoutSeconds: 5
                failureThreshold: 6

  3. 변경 사항 적용:

    helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

    LangSmith UI를 통해 만든 모든 사용자 배포가 이 레지스트리 자격 증명을 물려받아요.

레지스트리별 인증 방법은 프라이빗 레지스트리에서 이미지 가져오기에 대한 Kubernetes 문서를 참고하세요.

다른 네임스페이스의 Agent Server 로그 읽기

컨트롤 플레인(host-backend)과 데이터 플레인(listener)이 다른 Kubernetes 클러스터에 배포된 셀프 호스팅 배포에서는 서버 로그 검색이 지원되지 않아요.

컨트롤 플레인과 데이터 플레인이 같은 클러스터에 있는 배포의 경우, 컨트롤 플레인 Kubernetes 배포(host-backend)가 Agent Server 배포가 존재하는 네임스페이스의 Kubernetes deployments, pods, replicasets, logs를 get, list, watch할 권한이 있는지 확인하세요. 이를 달성하는 여러 방법이 있어요. 다음 예시는 Kubernetes RBAC를 사용하지만, 사용 사례에 가장 잘 맞는 접근 방식을 사용하세요:

  1. 필요한 권한으로 Role 만들기: Agent Server 네임스페이스에 Role을 만드세요. <data_plane_namespace>를 바꾸세요:

    kubectl apply -n <data_plane_namespace> -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: read-agent-server-logs-role
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get","list","watch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get","watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get","list","watch"]
- apiGroups: ["apps"]
  resources: ["replicasets"]
  verbs: ["get","list","watch"]
EOF

  2. 컨트롤 플레인 ServiceAccount 가져오기: <control_plane_namespace>를 바꾸세요:

    kubectl get serviceaccounts -n <control_plane_namespace> | grep host-backend

  3. Role을 컨트롤 플레인 ServiceAccount에 바인딩: <data_plane_namespace>, <control_plane_namespace>, <control_plane_service_account>를 바꾸세요:

    kubectl apply -n <data_plane_namespace> -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-agent-server-logs-role-binding
subjects:
- kind: ServiceAccount
  name: <control_plane_service_account>
  namespace: <control_plane_namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: read-agent-server-logs-role
EOF

이 예시에서 Role과 RoleBinding은 Agent Server 배포와 같은 Kubernetes 네임스페이스에 정의돼요. Role과 RoleBinding에 임의의 이름을 지정하고 필요에 따라 커스터마이즈할 수 있어요.

다음 단계

LangSmith Deployment가 활성화되면 컨트롤 플레인으로 배포를 참고해 LangSmith UI를 통해 애플리케이션을 만들고 배포하세요.

더 알아보기 (Learn more)