관리 개요
관리 개요 (Administration overview)
이 개요는 LangSmith 내에서 사용자, 조직, 워크스페이스, 애플리케이션을 관리하는 것과 관련된 주제를 다뤄요. 리소스 계층, 사용자 관리와 RBAC, 모범 사례, 사용량과 결제를 정리해 드릴게요.
출처: 문서
본문
이 개요는 LangSmith 내에서 사용자, 조직, 워크스페이스, 애플리케이션을 관리하는 것과 관련된 주제를 다룹니다.
리소스 계층
조직 (Organizations)
조직은 LangSmith 내 사용자의 논리적 그룹으로, 모든 워크스페이스에 적용되는 공유 설정을 정의합니다. 이러한 설정은 워크스페이스 내 개별 프로젝트가 아닌 조직 전반의 문제를 다룹니다. 일반적인 조직 수준 구성에는 사용자 관리, 단일 로그온(SSO), OAuth 제공자 구성, 커스텀 역할 생성, 결제, 사용량 추적이 포함됩니다. 일반적으로 회사당 조직이 하나입니다. 조직은 여러 워크스페이스를 가질 수 있습니다. 자세한 내용은 설정 가이드를 참고하세요.
처음 로그인하면 개인 조직(personal organization)이 자동으로 생성됩니다. 다른 사람과 협업하고 싶다면 별도의 조직을 만들고 팀 구성원을 초대할 수 있습니다. 개인 조직과 공유 조직 사이에는 몇 가지 중요한 차이점이 있습니다:
| 기능 | 개인 | 공유 |
|---|---|---|
| 최대 워크스페이스 | 1 | 요금제에 따라 다름 (pricing 페이지 참고) |
| 협업 | 사용자 초대 불가 | 사용자 초대 가능 |
| 결제: 유료 요금제 | Developer 요금제만 | 다른 모든 요금제 사용 가능 |
워크스페이스 (Workspaces)
참고: 워크스페이스는 이전에 Tenants라고 불렸습니다. 일부 코드와 API는 전환 기간 동안 옛 이름을 계속 참조할 수 있습니다.
워크스페이스는 조직 내 사용자와 리소스의 논리적 그룹입니다. 워크스페이스는 일반적으로 팀이나 사업 단위를 격리하는 데 사용되며, 프로젝트와 관련 리소스 사이에 분리를 제공합니다. 워크스페이스는 리소스와 접근 제어에 대한 신뢰 경계를 분리합니다. 사용자는 워크스페이스 수준에서 권한을 부여받으며, 이는 트레이싱 프로젝트, 데이터셋, 어노테이션 큐, 프롬프트를 포함한 해당 워크스페이스의 리소스에 대한 접근을 결정합니다. 설정에 대한 내용은 설정 가이드, 권한에 대한 내용은 워크스페이스 (RBAC)를 참고하세요.
조직 내 각 팀마다 별도의 워크스페이스를 만드는 것을 권장합니다. 리소스를 더 세분화하려면 애플리케이션을 사용해 워크스페이스 내에서 리소스를 그룹화할 수 있습니다. 팀의 격리 요구 사항에 따른 다양한 워크스페이스 구성 모델에 대한 지침은 워크로드 격리를 참고하세요.
애플리케이션 (Applications)
애플리케이션은 워크스페이스 내 리소스의 논리적 그룹입니다. 애플리케이션은 종종 에이전트이지만, 팀 내 어떤 프로젝트에도 사용할 수 있습니다. 애플리케이션은 현재 컨텍스트에 있는 애플리케이션과 관련된 리소스만 표면화하여 UI를 정리합니다.
애플리케이션은 리소스 태그 위에 구축되며, ABAC를 사용해 리소스 접근을 제어하는 데 사용할 수 있습니다.
LangSmith UI의 기본 내비게이션 사이드바에서 애플리케이션을 전환합니다. 사이드바 상단의 Application 드롭다운을 사용해 애플리케이션을 선택하세요.
어떤 리소스든 애플리케이션에 태그 없이 생성할 수 있습니다. 이러한 리소스는 All applications 옵션이 선택되었을 때 표시됩니다.
리소스 (Resources)
리소스는 트레이싱 프로젝트, 프롬프트, 데이터셋, 배포 같은 애플리케이션과 에이전트를 구축, 실행, 관찰하는 데 사용되는 구체적인 엔티티입니다. 리소스는 특정 애플리케이션에 범위가 지정됩니다.
추가 정보
다음 다이어그램은 조직, 워크스페이스, 애플리케이션, 리소스 간의 관계를 설명합니다: 
어떤 기능이 어떤 범위에서 사용 가능한지는 아래 표를 참고하세요:
| 리소스/설정 | 범위 |
|---|---|
| 트레이스 프로젝트 (Trace Projects) | 워크스페이스 또는 애플리케이션 |
| 어노테이션 큐 (Annotation Queues) | 워크스페이스 또는 애플리케이션 |
| 배포 (Deployments) | 워크스페이스 또는 애플리케이션 |
| 데이터셋 및 실험 (Datasets & Experiments) | 워크스페이스 또는 애플리케이션 |
| 프롬프트 (Prompts) | 워크스페이스 또는 애플리케이션 |
| 리소스 태그 (Resource Tags) | 워크스페이스 |
| API 키 (API Keys) | 워크스페이스 |
| 시크릿, 피드백 구성, 모델, 규칙, 공유 URL을 포함한 설정 | 워크스페이스 |
| 사용자 관리: 워크스페이스에 사용자 초대 | 워크스페이스 |
| RBAC: 워크스페이스 역할 할당 | 워크스페이스 |
| 데이터 보존, 사용량 한도 | 워크스페이스* |
| 요금제 및 결제, 크레딧, 인보이스 | 조직 |
| 사용자 관리: 조직에 사용자 초대 | 조직** |
| 워크스페이스 추가 | 조직 |
| 조직 역할 할당 | 조직 |
| RBAC: 커스텀 역할 생성/편집/삭제 | 조직 |
* 데이터 보존 설정과 사용량 한도는 곧 조직 수준에서도 제공될 예정입니다.
** 자체 호스팅 설치에서는 기능 플래그를 통해 조직에 워크스페이스 수준의 사용자 초대를 활성화할 수 있습니다. 자세한 내용은 자체 호스팅 사용자 관리 문서를 참고하세요.
리소스 태그 (Resource tags)
리소스 태그를 사용하면 ABAC와 함께 사용하기 위해 워크스페이스 내 리소스를 더 세분화할 수 있습니다. 각 태그는 리소스에 할당할 수 있는 키-값 쌍입니다.
LangSmith 리소스 태그는 AWS 같은 클라우드 서비스의 태그와 매우 유사합니다.
LangSmith UI에서 Settings로 이동해 사이드바의 Resource tags 페이지를 선택합니다.
사용자 관리 및 RBAC
사용자 (Users)
사용자는 LangSmith에 접근 권한이 있는 사람입니다. 사용자는 하나 이상의 조직과 그 조직 내 워크스페이스의 구성원이 될 수 있습니다.
조직 구성원은 Settings 페이지의 Members and roles 아래에서 관리됩니다.
워크스페이스 구성원은 Settings 아래의 Workspaces 페이지에서 관리됩니다.
API 키
경고: 2024년 10월 22일에
ls__접두사의 레거시 API 키 지원을 종료하고 개인 접근 토큰(PAT)과 서비스 키를 채택했습니다. 모든 새 통합에는 PAT와 서비스 키를 사용해야 합니다.ls__접두사의 API 키는 2024년 10월 22일부터 더 이상 작동하지 않습니다.
만료 날짜
API 키를 만들 때 만료 날짜를 설정할 수 있습니다. 키에 만료 날짜를 추가하면 보안이 강화되고 무단 접근 위험이 최소화됩니다. 예를 들어 향상된 접근이 필요한 임시 작업용 키에 만료 날짜를 설정할 수 있습니다.
기본적으로 키는 만료되지 않습니다. 만료된 API 키는 더 이상 유효하지 않으며 재활성화하거나 만료를 수정할 수 없습니다.
개인 접근 토큰 (PATs)
Personal Access Tokens(PAT)은 LangSmith API에 대한 요청을 인증하는 데 사용됩니다. 사용자가 만들고 사용자에 범위가 지정됩니다. PAT는 그것을 만든 사용자와 동일한 권한을 갖습니다. 애플리케이션에서의 요청 인증에는 이를 사용하지 않고, LangSmith API와 상호작용하는 개인 스크립트나 도구에 사용하는 것을 권장합니다. PAT와 연결된 사용자가 조직에서 제거되면 PAT는 더 이상 작동하지 않습니다.
PAT는 lsv2_pt_ 접두사를 가집니다.
구성원은 자신의 PAT를 비활성화, 재활성화 또는 삭제할 수 있습니다. Organization Admins과 Organization Operators는 모든 구성원의 PAT를 나열, 비활성화, 재활성화, 삭제할 수 있습니다.
토큰을 비활성화하면 인증이 중지되지만 기록, 소유자, 마지막 사용이 Deactivated 배지와 함께 표시됩니다. 비활성화는 되돌릴 수 있습니다. 삭제는 기록을 영구적으로 제거합니다. 재활성화는 원래 만료 날짜를 보존하며 해당 날짜가 지나면 불가능합니다. 인증 결과가 캐시되므로 이러한 변경은 즉시가 아닌 1분 이내에 적용됩니다. 서비스 키는 삭제만 가능하고 비활성화는 할 수 없습니다.
단계 및 인증 캐시 타이밍은 개인 접근 토큰 비활성화/삭제를 참고하세요.
서비스 키 (Service keys)
서비스 키는 PAT와 비슷하지만 서비스 계정을 대신해 LangSmith API에 대한 요청을 인증하는 데 사용됩니다. 서비스 키는 관리자만 만들 수 있습니다. LangGraph 에이전트나 다른 통합 같은 LangSmith API와 상호작용해야 하는 애플리케이션/서비스에 이를 사용하는 것을 권장합니다. 서비스 키는 단일 워크스페이스, 여러 워크스페이스 또는 조직 전체로 범위를 지정할 수 있으며, 접근 권한이 있는 워크스페이스(들)에 대해 LangSmith API 요청을 인증하는 데 사용할 수 있습니다.
서비스 키는 lsv2_sk_ 접두사를 가집니다.
경고: 대상 워크스페이스를 지정하려면
X-Tenant-Id헤더를 사용하세요.
- PAT 사용 시: 이 헤더를 생략하면 요청이 키와 연결된 기본 워크스페이스에 대해 실행됩니다.
- 조직 범위 서비스 키 사용 시: 워크스페이스 범위 리소스에 접근할 때
X-Tenant-Id헤더를 포함해야 합니다. 없으면403 Forbidden오류로 요청이 실패합니다.
참고: 서비스 키 또는 개인 접근 토큰을 만드는 방법은 설정 가이드를 참고하세요.
조직 역할 (Organization roles)
조직 역할은 Enterprise 기능 워크스페이스 RBAC와는 구별되며, 여러 워크스페이스의 맥락에서 사용됩니다. 조직 역할은 워크스페이스 구성원 특성과 조직 수준 권한을 결정합니다.
선택한 조직 역할은 다음과 같이 워크스페이스 구성원에도 영향을 줍니다:
- Organization Admin은 모든 조직 구성, 사용자, 결제, 워크스페이스를 관리할 수 있는 전체 접근 권한을 부여합니다.
- Organization Admin은 조직의 모든 워크스페이스에 대해
Admin접근 권한을 가집니다.
- Organization Admin은 조직의 모든 워크스페이스에 대해
- Organization User는 조직 정보를 읽을 수 있지만 조직 수준에서 쓰기 작업을 실행할 수는 없습니다. Organization User는 개인 접근 토큰을 만들 수 있습니다.
- Organization User는 워크스페이스 하위 집합에 추가되고 (RBAC가 활성화된 경우) 평소처럼 워크스페이스 역할을 할당받을 수 있으며, 이는 워크스페이스 수준의 권한을 지정합니다.
- Organization Viewer는 Organization User와 동일하지만 개인 접근 토큰을 만들 수 없습니다. (자체 호스팅의 경우 Helm 차트 버전 0.11.25+에서 사용 가능).
참고: Organization User와 Organization Viewer 역할은 Plus 및 Enterprise 요금제의 조직에서만 사용할 수 있습니다. Developer 조직(단일 워크스페이스)에서는 모든 사용자에게 기본적으로 Organization Admin 역할이 할당됩니다.
조직 전체에서 PAT 생성을 비활성화하는 방법은 보안 설정을 참고하세요.
조직과 워크스페이스 설정에 대한 자세한 내용은 조직 설정 가이드를 참고하세요.
다음 표는 조직 수준 권한의 개요를 제공합니다:
| Organization Viewer | Organization User | Organization Admin | |
|---|---|---|---|
| 조직 구성 보기 | ✅ | ✅ | ✅ |
| 조직 역할 보기 | ✅ | ✅ | ✅ |
| 조직 구성원 보기 | ✅ | ✅ | ✅ |
| 데이터 보존 설정 보기 | ✅ | ✅ | ✅ |
| 사용량 한도 보기 | ✅ | ✅ | ✅ |
| 개인 접근 토큰 (PAT) 만들기 | ❌ | ✅ | ✅ |
| 모든 구성원의 PAT 보기/비활성화/재활성화/삭제 | ❌ | ❌ | ✅ |
| 모든 워크스페이스에 대한 Admin 접근 | ❌ | ❌ | ✅ |
| 결제 설정 관리 | ❌ | ❌ | ✅ |
| 워크스페이스 만들기 | ❌ | ❌ | ✅ |
| 조직 역할 생성/편집/삭제 | ❌ | ❌ | ✅ |
| 조직에 새 사용자 초대 | ❌ | ❌ | ✅ |
| 사용자 초대 삭제 | ❌ | ❌ | ✅ |
| 조직에서 사용자 제거 | ❌ | ❌ | ✅ |
| 데이터 보존 설정 업데이트 | ❌ | ❌ | ✅ |
| 사용량 한도 업데이트 | ❌ | ❌ | ✅ |
필요한 권한과 그 작업을 수행할 수 있는 작업/역할의 포괄적 목록은 조직 및 워크스페이스 레퍼런스를 참고하세요.
워크스페이스 역할 (RBAC)
참고: RBAC(역할 기반 접근 제어)는 Enterprise 고객만 사용할 수 있는 기능입니다. 이 기능에 관심이 있다면 영업팀에 문의하세요. 다른 요금제는 기본적으로 모든 사용자에게 Admin 역할을 사용합니다.
역할은 사용자가 워크스페이스 내에서 갖는 권한 집합을 정의하는 데 사용됩니다. 편집할 수 없는 세 가지 내장 시스템 역할이 있습니다:
- Workspace Admin은 워크스페이스 내 모든 리소스에 대한 전체 접근 권한을 가집니다.
- Workspace Editor는 워크스페이스 관리(사용자 추가/제거, 역할 변경, 서비스 키 구성)를 제외한 모든 권한을 가집니다.
- Workspace Viewer는 워크스페이스 내 모든 리소스에 대한 읽기 전용 접근 권한을 가집니다.
Organization admins은 다양한 리소스에 대한 특정 권한을 가진 커스텀 역할도 만들고 편집할 수 있습니다.
Organization Settings > Members and roles에서 역할을 관리하고 Roles 탭을 선택할 수 있습니다.
- 역할과 권한에 대한 포괄적 문서는 역할 기반 접근 제어 가이드를 참고하세요.
- 역할 할당/생성에 대한 자세한 내용은 사용자 관리 가이드를 참고하세요.
- 필요한 권한과 그 작업을 수행할 수 있는 작업/역할의 포괄적 목록은 조직 및 워크스페이스 레퍼런스를 참고하세요.
모범 사례
환경 분리
리소스 태그를 사용해 기본 태그 키 Environment와 다양한 환경 값(예: dev, staging, prod)으로 리소스를 환경별로 구성하세요. 환경 분리에 별도 워크스페이스를 사용하는 것은 권장하지 않습니다. 리소스는 워크스페이스 간에 공유될 수 없어, (프롬프트 같은) 리소스를 환경 간에 승격하지 못하게 하기 때문입니다.
참고: 프롬프트 관리를 위한 리소스 태그 vs 커밋 태그
두 유형의 태그 모두
dev,staging,prod같은 환경 용어를 사용할 수 있지만 목적이 다릅니다:
- 리소스 태그 (
Environment: prod): 워크스페이스 전체에서 리소스를 구성하고 필터링하는 데 사용합니다. 트레이싱 프로젝트, 데이터셋 및 기타 리소스(프롬프트 포함)에 리소스 태그를 적용해 환경별로 그룹화하면 UI에서 필터링이 가능합니다.- 커밋 태그 (
prod태그): 코드가 참조하는 프롬프트 버전을 관리하는 데 사용합니다. 커밋 태그는 프롬프트 기록의 특정 커밋을 가리키는 라벨입니다. 코드가 태그 이름으로 프롬프트를 가져올 때(예:client.pull_prompt("prompt-name:prod")) 해당 태그가 현재 가리키는 커밋을 검색합니다. 프롬프트를staging에서prod로 승격하려면 커밋 태그를 원하는 버전을 가리키도록 이동합니다.리소스 태그는 어떤 리소스가 환경에 속하는지 구성합니다. 커밋 태그는 코드를 변경하지 않고 코드가 참조하는 프롬프트의 어느 버전을 제어하게 합니다.
사용량 및 결제
데이터 보존
이 섹션은 LangSmith에서 데이터 보존이 어떻게 작동하고 어떻게 가격이 책정되는지 다룹니다.
보존이 중요한 이유
- 개인정보 보호: 유럽의 GDPR이나 캘리포니아의 CCPA 같은 많은 데이터 개인정보 보호 규정은 조직이 수집 목적에 더 이상 필요하지 않은 개인 데이터를 삭제하도록 요구합니다. 보존 기간을 설정하는 것은 이러한 규정 준수에 도움이 됩니다.
- 비용: LangSmith는 데이터 보존이 낮은 트레이스에 대해 더 적게 청구합니다. 자세한 내용은 지출 한도 적용 방법을 배워보세요.
팁: 트레이스를 보내기 전에 보존 등급을 계획하세요. 변경 사항은 새 트레이스에만 적용되며 기존 트레이스는 원래 등급을 유지합니다. 프로젝트 수준 기본 보존 변경을 참고하세요.
작동 방식
LangSmith는 데이터 보존에 따라 두 가지 트레이스 등급이 있으며 특성은 다음과 같습니다:
| 기본 (Base) | 확장 (Extended) | |
|---|---|---|
| 가격 | pricing 페이지 참고 | pricing 페이지 참고 |
| 보존 기간 | 14일 | 180일 |
경고: 2026년 9월 14일부터 SaaS 고객의 최대 장수명 트레이스 보존 기간이 180일로 변경됩니다. Enterprise 고객은 이 새로운 최대치까지 워크스페이스별 확장 보존 기간을 커스터마이즈할 수 있습니다. 변경 사항은 새 트레이스에만 적용되며 기존 트레이스는 영향을 받지 않습니다. 확장 보존 정책 커스터마이즈를 참고하세요.
보존 기간 종료 후 데이터 삭제
지정된 보존 기간 후에는 트레이스가 트레이싱 프로젝트 UI 또는 API에서 더 이상 접근할 수 없습니다. 트레이스와 관련된 모든 사용자 데이터(예: 입력과 출력)는 그 후 하루 이내에 내부 시스템에서 삭제됩니다. 각 트레이스와 관련된 일부 메타데이터는 분석 및 청구 목적으로 무기한 유지될 수 있습니다.
데이터 보존 자동 업그레이드
경고: 자동 업그레이드는 청구서에 영향을 줄 수 있습니다. 예상되는 LangSmith 트레이싱 비용을 완전히 이해하려면 이 섹션을 주의 깊게 읽어주세요.
대부분의 트레이스는 기본 보존을 사용합니다. 온라인 평가기와 자동화 규칙 같은 일부 동작은 트레이스를 더 높은 비용의 더 긴 보존 기간으로 연장할 수 있습니다. 어떤 동작이 보존을 연장하는지 여러분이 제어합니다.
base 등급 트레이스에서 특정 기능을 사용하면 그 데이터 보존이 자동으로 extended 등급으로 업그레이드될 수 있습니다. 이는 트레이스의 보존 기간과 비용을 모두 증가시킵니다.
동작별 보존 동작:
- API 또는 SDK를 통한 피드백: 명시적으로
extend_trace_retention=true를 전달하는(extendTraceRetention: true, TypeScript) API 또는 SDK 호출을 통해 트레이스의 어떤 런(또는 스레드의 어떤 트레이스)에든 피드백이 추가됩니다. 자세한 내용은 사용자 피드백 연결을 참고하세요. LangSmith UI는 보존을 연장하지 않고 피드백과 메모를 보냅니다. - 온라인 평가기: 온라인 평가기가 트레이스를 평가하고 그 보존 설정이 활성화됩니다. 트레이스 수준 및 스레드 수준 평가기 모두 이 업그레이드에서 탈퇴할 수 있습니다.
- 자동화 규칙: 보존 연장이 활성화된 자동화 규칙이 트레이스 내 어떤 런과도 일치합니다. 단일 런의 일치가 해당 런뿐 아니라 전체 트레이스를 업그레이드합니다. 항목 유형이 Threads인 규칙은 가장 최근 트레이스뿐 아니라 일치하는 스레드의 모든 트레이스를 업그레이드합니다.
- 수동 어노테이션 큐 추가 (업그레이드 없음): 어노테이션 큐에 런이나 스레드를 수동으로 추가하는 것은 기본적으로 보존을 업그레이드하지 않습니다.
이 변경은 새 동작에만 적용됩니다. 이전 동작으로 이미 업그레이드된 트레이스는 확장 보존을 유지합니다.
참고: 트레이싱 프로젝트에서 온라인 평가기를 만들거나 편집할 때, 그 평가기가 평가하는 트레이스의 업그레이드를 탈퇴하여 기본 보존을 유지할 수 있습니다. 이 옵션은 프로젝트의 기본 보존이 기본 등급일 때만 사용할 수 있습니다. 단계별 지침은 평가기 트레이스 보존 관리를 참고하세요.
참고: 보존 연장은 새 온라인 평가기와 자동화 규칙에서 기본적으로 활성화되어 있습니다. 각 평가기나 규칙을 구성할 때 탈퇴할 수 있습니다.
왜 트레이스를 자동 업그레이드하나요?
트레이싱 자동 업그레이드 모델에는 두 가지 이유가 있습니다:
- 이러한 조건 중 어떤 것과 일치하는 트레이스는 다른 트레이스보다 근본적으로 더 흥미롭다고 생각하며, 따라서 사용자가 더 오래 보관할 수 있는 것이 좋다고 생각합니다.
- 의미 있게 상호작용되지 않을 수 있는 트레이스에 대해서는 고객에게 훨씬 낮은 비용을 청구하고 싶습니다. 자동 업그레이드가 LangSmith가 제공하는 가치와 결제 모델을 정렬한다고 생각하며, 의미 있는 상호작용이 있는 트레이스만 더 높은 요율로 청구됩니다.
결제 모델에 대한 질문이나 우려가 있으면 support.langchain.com을 통해 지원팀에 문의해 의견을 알려주세요!
데이터 보존이 다운스트림 기능에 어떤 영향을 주나요?
다음 기능은 보존과 다르게 상호작용합니다:
- 실험: 런은 기본적으로 확장 보존으로 생성됩니다.
- 자동화 규칙과 평가기: 보존 설정이 활성화되면 일치하는 트레이스를 확장 보존으로 업그레이드합니다. 스레드 수준 규칙과 평가기는 일치하는 스레드의 모든 트레이스를 업그레이드합니다.
- UI 피드백, 메모, 어노테이션 큐: 트레이스의 보존 등급을 변경하지 않습니다.
다른 기능은 트레이스의 보존 등급과 독립적으로 작동합니다:
- 모니터링: base 등급 트레이스의 데이터 보존 기간이 끝난 후에도 모니터링 탭은 계속 작동합니다. 그것은 30일 이상 존재하는 트레이스 메타데이터로 구동되므로,
base등급 트레이스에서도 모니터링 그래프가 계속 정확하게 유지됩니다. - 데이터셋: 데이터셋은 무기한 데이터 보존 기간을 가집니다. 다시 말해 트레이스의 입력과 출력을 데이터셋에 추가하면 절대 삭제되지 않습니다. 데이터 수집에 LangSmith를 사용한다면 데이터셋 기능을 활용하는 것을 권장합니다.
결제 모델
청구 가능한 메트릭
LangSmith 인보이스에는 청구되는 두 가지 메트릭이 표시됩니다:
- LangSmith Traces (기본 요금)
- LangSmith Traces (확장 데이터 보존 업그레이드).
첫 번째 메트릭은 등급과 관계없이 모든 트레이스를 포함합니다. 두 번째 메트릭은 확장 보존 트레이스의 수만 계산합니다.
왜 base와 extended 트레이스 대신 모든 트레이스 + 업그레이드를 측정하나요?
결제를 고려할 때 자연스러운 질문은 인보이스에 base 등급과 extended 등급 트레이스의 수를 직접 표시하지 않는 이유입니다.
더 직관적일 것이라는 점은 이해하지만, 그것은 트레이스 업그레이드를 제대로 수용하지 못합니다. 6월 30일에 기록된 base 등급 트레이스가 7월 3일에 extended 등급으로 업그레이드된 경우를 생각해 봅시다. base 등급 트레이스는 6월 결제 기간에 발생했지만, 업그레이드는 7월 결제 기간에 발생했습니다. 따라서 고객에게 올바르게 청구하려면 이 두 이벤트를 독립적으로 측정할 수 있어야 합니다.
트레이스가 확장 보존 트레이스로 기록된 경우 base와 extended 메트릭이 모두 같은 타임스탬프로 기록됩니다.
속도 제한
LangSmith에는 모든 사용자를 위한 서비스 안정성을 보장하도록 설계된 속도 제한이 있습니다.
접근과 안정성을 보장하기 위해 LangSmith는 다음 상황에서 속도 또는 사용량 제한이 초과되었음을 나타내는 HTTP 상태 코드 429로 응답합니다:
애플리케이션 로드 밸런서에서의 1분 임시 처리량 제한
이 429는 서비스 키 또는 PAT 기준으로 1분 창에서 고정된 수의 API 호출을 초과한 결과입니다. 창의 시작은 약간 다를 수 있으며, 시계 분의 시작과 일치한다는 보장은 없고 애플리케이션 배포 이벤트에 따라 달라질 수 있습니다.
최대 이벤트를 받은 후 평가 창 시작부터 60초가 될 때까지 429로 응답하고, 그 후 과정이 반복됩니다.
이 429는 애플리케이션 로드 밸런서가 발생시키며, 요금제 등급과 관계없이 모든 LangSmith 사용자에 대해 모든 사용자의 서비스 연속성을 보장하는 메커니즘입니다.
| 메서드 | 엔드포인트 | 한도 | 창 |
|---|---|---|---|
DELETE |
/sessions* |
30 | 1분 |
POST OR PATCH |
/runs* |
5000 | 1분 |
GET |
/runs/:id |
30 | 1분 |
POST |
/feedbacks* |
5000 | 1분 |
* |
* |
2000 | 1분 |
참고: LangSmith SDK는 단일 세션 ID에서 최대 100개의 런을 단일 API 호출로 배치하여 런 관련 엔드포인트에서 이러한 한도에 도달할 가능성을 최소화합니다.
요금제 수준 시간별 트레이스 이벤트 한도
이 429는 최대 시간별 수집 이벤트에 도달한 결과이며, UTC 시계 시간 시작에 시작해 새 시간마다 초기화되는 고정 창에서 평가됩니다.
이 맥락의 이벤트는 런의 생성 또는 업데이트입니다. 런이 생성된 후 같은 시간별 창에서 업데이트되면 이 한도에 대해 2개의 이벤트로 계산됩니다.
이것은 애플리케이션이 발생시키며 요금제 등급별로 다릅니다. Startup/Plus 및 Enterprise 요금제의 조직은 개인용으로 설계된 Free 및 Developer 요금제보다 높은 시간별 한도를 가집니다.
| 요금제 | 한도 | 창 |
|---|---|---|
| Developer (결제 등록 없음) | 50,000 이벤트 | 1시간 |
| Developer (결제 등록 있음) | 250,000 이벤트 | 1시간 |
| Startup/Plus | 500,000 이벤트 | 1시간 |
| Enterprise | 커스텀 | 커스텀 |
요금제 수준 시간별 트레이스 데이터 수집 한도
이 429는 트레이스 입력, 출력, 메타데이터 전체에서 수집된 최대 데이터 양에 도달한 결과이며, UTC 시계 시간 시작에 시작해 새 시간마다 초기화되는 고정 창에서 평가됩니다.
일반적으로 입력, 출력, 메타데이터는 런 생성과 업데이트 이벤트 모두에 전송됩니다. 런이 2.0MB로 생성되고 같은 시간별 창에서 3.0MB로 업데이트되면 이 한도에 대해 5.0MB의 저장소로 계산됩니다.
이것은 애플리케이션이 발생시키며 요금제 등급별로 다릅니다. Startup/Plus 및 Enterprise 요금제의 조직은 개인용으로 설계된 Free 및 Developer 요금제보다 높은 시간별 한도를 가집니다.
| 요금제 | 한도 | 창 |
|---|---|---|
| Developer (결제 등록 없음) | 500MB | 1시간 |
| Developer (결제 등록 있음) | 2.5GB | 1시간 |
| Startup/Plus | 5.0GB | 1시간 |
| Enterprise | 커스텀 | 커스텀 |
요금제 수준 월별 고유 트레이스 한도
이 429는 최대 월별 수집 트레이스에 도달한 결과이며, UTC 달력 월 시작에 시작해 새 달이 시작될 때 초기화되는 고정 창에서 평가됩니다.
이것은 애플리케이션이 발생시키며 결제 수단이 등록되지 않은 Developer 요금제 등급에만 적용됩니다.
| 요금제 | 한도 | 창 |
|---|---|---|
| Developer (결제 등록 없음) | 5,000 트레이스 | 1달 |
자체 구성 월별 사용량 한도
이 429는 조직 관리자가 구성한 사용량 한도에 도달한 결과이며, UTC 달력 월 시작에 시작해 새 달이 시작될 때 초기화되는 고정 창에서 평가됩니다.
이것은 애플리케이션이 발생시키며 구성된 설정에 따라 조직별로 다릅니다.
트레이스당 최대 런
프로덕션 워크로드에 대한 보호.
런 쿼리 엔드포인트
POST /runs/query 엔드포인트에는 쿼리 매개변수에 따른 추가적인 테넌트별 속도 제한이 있습니다. 자세한 내용은 SDK로 트레이스 쿼리를 참고하세요.
애플리케이션에서 429 응답 처리
일부 429 응답은 일시적이며 연속 호출에서 성공할 수 있으므로, 애플리케이션에서 LangSmith API를 직접 호출한다면 지수 백오프와 지터가 있는 재시도 로직을 구현할 것을 권장합니다.
편의상 LangSmith SDK로 구축된 LangChain 애플리케이션에는 이 기능이 내장되어 있습니다.
참고: 엔드포인트를 장기간 포화시키면 재시도가 효과적이지 않을 수 있다는 점을 유의하세요. 애플리케이션이 결국 모든 재시도를 소진할 만큼 큰 백로그를 쌓게 되기 때문입니다.
그런 경우 우리는 여러분의 요구를 더 구체적으로 논의하고 싶습니다. LangSmith Support로 애플리케이션의 처리량 요구와 샘플 코드에 대한 세부 정보를 보내주세요. 버그 수정, 애플리케이션 코드 변경, 또는 다른 LangSmith 요금제 중 어느 것이 가장 좋은지 함께 파악할 수 있습니다.
사용량 한도
LangSmith는 트레이싱에 대한 사용량 한도를 구성할 수 있게 합니다. 이는 지출 한도가 아닌 사용량 한도이며, 총 지출 금액이 아니라 어떤 이벤트의 발생 횟수를 제한할 수 있음을 의미합니다.
LangSmith는 앞서 언급한 데이터 보존 가이드에서 다룬 청구 가능한 메트릭을 반영하는 두 가지 월별 한도를 설정하게 합니다:
- 모든 트레이스 한도
- 확장 데이터 보존 트레이스 한도
이들은 각각 총 트레이스 수와 확장 데이터 보존 트레이스 수를 제한합니다.
참고: 평가기 런의 지출 한도에 대해서는 평가기 지출 추적 및 제한을 참고하세요.
사용량 제한의 특성
사용량 제한은 근사적입니다. 즉 한도의 정확성을 보장하지 않습니다. 드물게, 사용량 제한이 적용되기 전에 추가 트레이스가 임계값 위에서 처리되는 짧은 시간이 있을 수 있습니다.
확장 데이터 보존 트레이스 한도의 부작용
확장 데이터 보존 트레이스 한도에는 부작용이 있습니다. 한도에 이미 도달하면 트레이싱 등급의 자동 업그레이드를 일으킬 수 있는 어떤 기능도 접근할 수 없게 됩니다. 이는 트레이스의 자동 업그레이드가 또 다른 확장 보존 트레이스를 생성하게 되며, 이는 한도가 허용하지 않아야 하기 때문입니다. 따라서 다음을 더 이상 할 수 없습니다:
- 런 규칙 일치
- 트레이스에 피드백 추가
- 어노테이션 큐에 런 추가
이 각 기능은 자동 업그레이드를 일으킬 수 있으므로, 한도에 도달하면 이를 차단합니다.
사용량 한도 업데이트
사용량 한도는 Settings 페이지의 Usage and Billing 아래에서 업데이트할 수 있습니다. 한도 값은 캐시되므로 새 한도가 적용되기까지 1~2분이 걸릴 수 있습니다.
프로젝트별 및 사용자별 트레이스 한도
워크스페이스 전체 한도 외에도 단일 트레이싱 프로젝트 또는 개별 워크스페이스 멤버에 대해 월별 트레이스를 제한할 수 있습니다. 이렇게 하면 한 프로젝트나 사용자가 워크스페이스의 트레이싱 예산을 불균형하게 소비하지 않게 방지합니다.
이러한 한도를 구성하려면 Settings를 열고 Usage configuration으로 이동해 Project & user limits 탭을 선택합니다. Add limit을 선택한 다음 설정합니다:
- Scope: 단일 트레이싱 프로젝트를 제한하려면 Project, 단일 워크스페이스 멤버를 제한하려면 User.
- Workspace: 프로젝트나 멤버를 포함하는 워크스페이스.
- Project 또는 User: 제한할 대상.
- Monthly trace limit: 달력 월당 허용되는 최대 트레이스 수.
이러한 한도를 업데이트하려면 워크스페이스 사용량 한도와 같은 권한(Update usage limits)이 필요합니다.
워크스페이스 한도와 마찬가지로 프로젝트별/사용자별 한도는 UTC 달력 월별로 평가되며 새 달이 시작될 때 초기화됩니다. 프로젝트나 사용자가 한도에 도달하면 새 트레이스는 버려지고 한도가 초기화될 때까지 다시 수집되지 않습니다. 적용은 근사적이므로 한도가 적용되기 전에 소수의 트레이스가 임계값 위에서 처리될 수 있습니다. 이러한 한도는 Cloud와 Self-hosted 모두에 적용됩니다.
참고: 프로젝트별/사용자별 한도는 워크스페이스 전체 및 요금제 한도에 추가됩니다. 트레이스는 적용 가능한 모든 한도 내에 있어야 수집됩니다.
사용자별 한도는 특정 워크스페이스 멤버에 귀속된 트레이스만 계산합니다. 멤버에 연결되지 않은 API 키나 서비스 키로 보낸 트레이스는 사용자별 한도에 계산되지 않습니다.
한도 값은 캐시되므로 새 또는 변경된 한도가 적용되기까지 1~2분이 걸릴 수 있습니다.
관련 내용
- 지출 한도 적용 튜토리얼
더 알아보기
- 릴리스 정책 (Release policy): 자체 호스팅 릴리스 채널, 주기, 버전 번호에 대해 알아보세요.
더 알아보기
- 자세한 RBAC 문서는 Role-based access control 문서를 참고하세요.
- 지출 한도 적용은 Manage billing 문서를 확인해 보세요.