Terraform으로 LangSmith 관리하기

Terraform으로 LangSmith 관리하기

공식 LangSmith Terraform 프로바이더를 사용해 워크스페이스, 접근 제어, 리소스 태그, 평가자, 실행 규칙, 알림 규칙을 코드로 관리하는 방법을 알려드릴게요.

공식 LangSmith Terraform 프로바이더는 LangSmith 조직과 워크스페이스 리소스를 코드로 관리하게 합니다: 워크스페이스, 커스텀 역할, 조직·워크스페이스 구성원, 리소스 태그, 접근 정책, 평가자, 실행 규칙, 알림 규칙. 이것은 API로 조직을 관리하는 것의 infrastructure-as-code 대응물입니다.

참고: 리소스 태그와 접근 정책 관리에는 LangSmith Terraform 프로바이더 v0.0.6 이상이 필요합니다.

확인: 본격적으로 시작하기 전에 다음을 읽는 것이 도움이 됩니다:

출처: 문서

본문

설치 및 구성

프로바이더를 Terraform 구성에 추가하고 버전을 고정합니다:

terraform {
  required_providers {
    langsmith = {
      source  = "langchain-ai/langsmith"
      version = "~> 0.0.6"
    }
  }
}

provider "langsmith" {
  # Cloud (US). Use https://eu.api.smith.langchain.com for the EU region,
  # or your self-hosted URL. Can also be set via LANGSMITH_ENDPOINT.
  api_url = "https://api.smith.langchain.com"

  # Optional: scope workspace-level resources to a specific workspace.
  workspace_id = "00000000-0000-0000-0000-000000000000"
}

그런 다음 terraform init를 실행해 프로바이더를 다운로드합니다.

인증

프로바이더는 LangSmith SDK와 CLI와 동일한 방식으로 자격 증명을 해석합니다. api_key를 하드코딩하는 것보다 환경 변수나 프로필을 선호하세요:

  • 환경—LANGSMITH_API_KEY, LANGSMITH_ENDPOINT(API URL), LANGSMITH_WORKSPACE_ID.
  • 프로필—LangSmith CLI 프로필을 사용하려면 profile(또는 LANGSMITH_PROFILE)을 설정합니다.
  • 프로바이더 인자—api_key, api_url, workspace_id, profile.

LangSmith 설정에서 API 키 또는 서비스 키를 만듭니다. 사용 가능한 키 유형은 인증 방법을 참고하세요.

경고: 워크스페이스 생성, 조직 구성원 초대, 접근 정책 관리 같은 조직 범위 작업에는 Organization Admin 권한이 있는 조직 범위 서비스 키가 필요합니다. 워크스페이스 구성원, 리소스 태그, 평가자, 실행 규칙 같은 워크스페이스 범위 리소스를 대상으로 하려면 workspace_id(또는 LANGSMITH_WORKSPACE_ID)를 설정하세요.

예제

워크스페이스 만들기

resource "langsmith_workspace" "demo" {
  display_name  = "Demo Workspace"
  tenant_handle = "demo-workspace"
}

역할과 구성원 관리

데이터 소스로 빌트인 역할을 조회한 뒤 배정합니다. 이는 사용자를 조직에 초대하고 워크스페이스에서 관리자 권한을 부여합니다:

data "langsmith_org_role" "user" {
  name = "ORGANIZATION_USER"
}

data "langsmith_workspace_role" "admin" {
  name = "WORKSPACE_ADMIN"
}

resource "langsmith_org_membership" "alice" {
  email   = "[email protected]"
  role_id = data.langsmith_org_role.user.id
}

resource "langsmith_workspace_membership" "alice_demo" {
  workspace_id = langsmith_workspace.demo.id
  email        = langsmith_org_membership.alice.email
  role_id      = data.langsmith_workspace_role.admin.id
}

예를 들어 기존 역할의 권한을 복제해 커스텀 워크스페이스 역할을 정의할 수도 있습니다:

resource "langsmith_workspace_role" "issues_agent" {
  display_name = "Issues Agent"
  description  = data.langsmith_workspace_role.admin.description
  permissions  = data.langsmith_workspace_role.admin.permissions
}

리소스 태그와 접근 정책 관리

리소스 태그를 사용해 워크스페이스 리소스를 조직화하고 속성 기반 접근 제어(ABAC)를 적용합니다. langsmith_tag 편의 리소스는 하나의 태그 키와 값을 소유합니다. 키나 값이 구성 간에 공유될 때는 독립 langsmith_tag_key와 langsmith_tag_value 리소스를 사용하세요.

다음 구성은 Environment=production 태그를 만들고 트레이싱 프로젝트에 적용하며, 워크스페이스 역할을 프로덕션 프로젝트로 제한합니다:

resource "langsmith_tag" "production" {
  key               = "Environment"
  value             = "production"
  key_description   = "Deployment environment"
  value_description = "Production workloads"
}

resource "langsmith_tagging" "production_project" {
  tag_value_id  = langsmith_tag.production.tag_value_id
  resource_type = "project"
  resource_id   = "00000000-0000-0000-0000-000000000000" # tracing project ID
}

resource "langsmith_workspace_role" "production_reader" {
  display_name = "Production Reader"
  description  = "Can read production projects"
  permissions  = ["projects:read"]
}

resource "langsmith_access_policy" "production_readers" {
  name        = "Production readers"
  description = "Read access to production projects"
  effect      = "allow"

  condition_groups = [{
    permission    = "projects:read"
    resource_type = "project"
    conditions = [{
      attribute_name  = "resource_tag_key"
      attribute_key   = "Environment"
      operator        = "equals"
      attribute_value = "production"
    }]
  }]
}

resource "langsmith_access_policy_attachment" "production_reader" {
  role_id          = langsmith_workspace_role.production_reader.id
  access_policy_id = langsmith_access_policy.production_readers.id
}

평가자, 실행 규칙, 알림 자동화

프로바이더는 계정 이상을 관리합니다. 온라인 코드 평가자, 이를 적용하는 실행 규칙, 알림을 워크스페이스와 함께 코드화할 수 있습니다:

resource "langsmith_evaluator" "tool_calls" {
  workspace_id = langsmith_workspace.demo.id
  name         = "tool call counts"
  type         = "code"

  code_evaluator = {
    language = "javascript"
    code     = file("${path.module}/evaluator.js")
  }
}

# A run rule applies the evaluator to matching runs in a tracing project.
# Run rules can also add runs to a dataset or annotation queue, or call webhooks.
resource "langsmith_run_rule" "score_root_runs" {
  workspace_id  = langsmith_workspace.demo.id
  display_name  = "score root runs"
  session_id    = "00000000-0000-0000-0000-000000000000" # tracing project ID
  sampling_rate = 1
  filter        = "eq(is_root, true)"

  evaluator_id = langsmith_evaluator.tool_calls.id
}

resource "langsmith_alert_rule" "error_rate" {
  session_id     = "00000000-0000-0000-0000-000000000000" # tracing project ID
  name           = "run error count high"
  type           = "threshold"
  attribute      = "error_count"
  aggregation    = "sum"
  window_minutes = 15
  operator       = "gte"
  threshold      = 10
  filter         = "eq(is_root, true)"

  actions = [{
    target  = "webhook"
    url_env = "LANGSMITH_ALERTS_WEBHOOK_URL"
    config_json = jsonencode({
      body = jsonencode({ text = "Error rate elevated" })
    })
  }]
}

리소스 레퍼런스

모든 인자와 속성을 가진 전체 리소스·데이터 소스 목록은 Terraform Registry에 게시·동기화되어 있습니다:

Terraform Registry의 LangSmith 프로바이더 — 모든 리소스와 데이터 소스의 전체 레퍼런스 보기: https://registry.terraform.io/providers/langchain-ai/langsmith/latest/docs

더 알아보기