모델 구성 관리하기

모델 구성을 관리하고 LangSmith 기능 전반에서 가용성을 제어하는 방법을 알려드릴게요.

모델 구성은 LangSmith 기능이 AI 프로바이더를 호출할 때 사용하는 모델과 파라미터를 정의합니다. 공유된 단일 구성 라이브러리가 전체 워크스페이스에 걸쳐 있으므로, 만든 구성은 중복 없이 다음 기능 전반에서 사용할 수 있습니다:

워크스페이스 관리자는 구성을 생성·편집·삭제하고 기능별로 사용 가능한 프로바이더와 모델을 제어할 수 있습니다. 관리자가 아닌 구성원은 구성을 볼 수 있지만 수정할 수 없습니다.

구성은 OAuth 클라이언트 자격 증명도 담을 수 있어서, 정적 API 키를 사용하는 대신 요청 시점에 IdP에 대해 단기 bearer 토큰을 발급받습니다.

출처: 문서

본문

기능 접근(Feature Access)

Feature Access 테이블은 각 LangSmith 기능에 대해 프로바이더와 모델 가용성을 독립적으로 제어합니다.

Feature	Model selection experience
Playground	Full model controls—view and adjust all parameters. No built-in models; relies on workspace configurations.
Evaluators	Full model controls—view and adjust all parameters. No built-in models; relies on workspace configurations.
Fleet	Choose from a curated list by default. You can also add custom workspace configurations.
Chat	Choose from a curated list by default. You can also add custom workspace configurations.
Insights (Thinking)	Model used for deep analysis. Choose from a curated list with provider recommendations by default. You can also add custom workspace configurations.
Insights (Summarization)	Model used for lightweight summarization. Choose from a curated list with provider recommendations by default. You can also add custom workspace configurations.

모든 기능은 커스텀 워크스페이스 구성을 지원하므로 기본적으로 큐레이션된 목록을 보여주는 기능에서도 어떤 프로바이더나 모델이든 사용할 수 있습니다.

참고: Insights는 두 개의 별도 행을 사용합니다 — 하나는 분석용, 하나는 요약용. UI는 어느 행에 대해 비호환 프로바이더나 비권장 모델을 선택하면 경고를 표시합니다.

기능 접근 구성

UI에서 기능 접근을 구성하려면:

Settings > Model configurations로 이동합니다.
Feature Access 테이블에서 구성하려는 기능을 찾습니다.
Enabled Providers를 클릭해 해당 기능에 대해 프로바이더를 켜거나 끕니다.
Available Models를 클릭해 사용자가 선택할 수 있는 모델을 고릅니다.
Default Model 드롭다운을 사용해 사용자가 기능을 열 때 사전 선택되는 모델을 설정합니다.

참고: Settings > Model providers에서 조직 전체에 대해 비활성화된 프로바이더는 이 테이블에서 잠긴 것으로 나타나며 워크스페이스별로 다시 활성화할 수 없습니다. 조직 전체 프로바이더 제어를 참고하세요.

조직 전체 프로바이더 제어

프로바이더 가용성은 두 수준에서 제어됩니다:

조직(조직 관리자): 전체 조직 — 모든 워크스페이스와 모든 기능에 대해 프로바이더를 켜거나 끕니다. Settings > Model providers에서 관리.
워크스페이스(워크스페이스 관리자): 단일 워크스페이스 내에서 기능별로 프로바이더·모델 가용성을 제어하는 위의 Feature Access 테이블.

조직 수준이 우선합니다. 조직에 대해 비활성화된 프로바이더는 모든 워크스페이스와 모든 기능에서 사용할 수 없으며, 각 워크스페이스의 Feature Access 테이블에서 잠김(locked) 으로 표시됩니다 — 워크스페이스 관리자는 볼 수 있지만 다시 활성화할 수 없습니다. 워크스페이스는 조직이 허용하는 프로바이더 중에서만 선택합니다.

조직 전체 프로바이더 관리는 Organization Admin 역할(organization:manage 권한)이 필요하며, LangSmith Cloud와 Self-hosted에서 조직(개인 계정이 아닌)에 사용할 수 있습니다.

조직에 대한 프로바이더 비활성화

Settings 아래의 Model providers 페이지로 이동합니다.
프로바이더를 꺼서 조직 전체에서 비활성화하거나 켜서 다시 활성화합니다.

조직 범위 모델 구성

참고: 조직 범위 모델 구성은 LangSmith Self-hosted와 Cloud Enterprise에서만 사용할 수 있습니다.

조직 관리자는 조직 수준에서 모델 구성을 만들 수 있으므로, 단일 구성이 워크스페이스별로 복제하지 않고 조직의 모든 워크스페이스에서 사용 가능합니다.

조직 범위 구성은 각 워크스페이스의 Settings > Model configurations 페이지의 Configurations 테이블에서 워크스페이스 범위 구성과 함께 나타납니다. 조직 범위 구성을 Fleet, Playground, Evaluators 또는 다른 기능에서 사용할 수 있게 하려면 워크스페이스 관리자가 해당 워크스페이스의 Feature Access 테이블에서 활성화해야 합니다.

조직 범위 구성 만들기

조직 범위 구성을 만들려면 Organization Admin 역할이 필요합니다:

조직 수준에서 Settings > Model configurations로 이동합니다.
Configurations 아래에서 + Create를 클릭합니다.
Provider와 Model을 선택하고 나머지 필드를 완료합니다.
Save를 클릭합니다.

워크스페이스에서 조직 범위 구성 활성화

조직 범위 구성을 만든 뒤 워크스페이스 기능에 나타나기 전에 워크스페이스 관리자가 활성화해야 합니다:

워크스페이스에서 Settings > Model configurations로 이동합니다.
Configurations 테이블에서 조직 범위 구성을 찾습니다.
Feature Access 테이블에서 나타나야 하는 각 기능에 대해 구성을 활성화합니다.

제한사항

조직 범위 구성으로 작업할 때 다음 제약을 기억하세요:

범위는 불변입니다. 조직 범위로 저장된 구성은 워크스페이스 범위로 변경할 수 없고, 워크스페이스 범위 구성은 조직 범위로 승격할 수 없습니다. 범위를 변경해야 하면 새 구성을 만드세요.
이름 충돌 시 워크스페이스가 우선합니다. 워크스페이스 구성과 조직 범위 구성이 같은 이름을 공유하면 워크스페이스 버전이 우선합니다.
시크릿 저장 위치. LangChain Cloud(비-BYOC)에서 조직 범위 구성의 시크릿은 LangChain Cloud control plane에 저장됩니다. BYOC 배포에서는 데이터 플레인 스위처를 사용해 모델 시크릿이 기록되는 위치를 구성할 수 있습니다.

구성(Configurations)

Configurations 테이블은 워크스페이스용 명명된 모델 구성의 공유 라이브러리입니다. LangSmith에서(Playground에서 포함) 만든 구성이 여기에 나타나며 모든 기능에서 재사용할 수 있습니다.

구성 만들기

Settings > Model configurations로 이동합니다.
Configurations 아래에서 + Create를 클릭합니다.
Provider와 Model을 선택합니다.
API Key Name을 입력합니다 — 프로바이더 API 키를 저장하는 워크스페이스 시크릿의 이름.
필요에 따라 파라미터를 조정합니다. 파라미터는 섹션으로 그룹화됩니다:
- 표준 샘플링 설정: temperature, top P, top K, presence penalty, frequency penalty, max output tokens
- 추론(Reasoning): reasoning effort, service tier
- 프로바이더 구성: provider API, base URL
- 옵션: stop sequences, seed, JSON mode, extra headers, requests per second, extra parameters 사용 가능한 파라미터는 프로바이더에 따라 다릅니다 — 자세한 내용은 프로바이더 문서를 참고하세요.
Save를 클릭합니다.

구성 편집

Configurations 테이블에서 구성 옆의 오버플로우 메뉴 를 클릭합니다.
Edit를 선택합니다.
구성을 업데이트하고 Save를 클릭합니다.

구성 삭제

Configurations 테이블에서 구성 옆의 오버플로우 메뉴 를 클릭합니다.
Delete를 선택하고 확인합니다.

OAuth 클라이언트 자격 증명

참고: OAuth 클라이언트 자격 증명은 버전 0.16.0-rc.6 이상을 실행하는 LangSmith Cloud와 Self-hosted 배포에서 사용할 수 있습니다.

모델 구성이 OAuth2 게이트웨이 뒤에 있으면 정적 API 키를 배포하는 대신 OAuth client_credentials를 구성에 직접 저장할 수 있습니다. LangSmith는 요청 시점에 해당 자격 증명을 단기 bearer 토큰으로 교환하고, 발신 LLM 호출에 Authorization: Bearer로 첨부하며, 만료 전에 토큰을 갱신합니다. 이는 워크스페이스를 LLM auth proxy로 라우팅하는 것의 구성별 셀프 서비스 대안입니다. 둘은 구성별로 상호 배타적입니다.

OAuth 클라이언트 자격 증명은 커스텀 모델 구성을 지원하는 모든 요금제에서 사용할 수 있습니다. Use Custom OAuth 토글은 bearer 토큰 프로바이더(OpenAI, Anthropic, OpenAI 호환 엔드포인트 등)에 적용되며 Bedrock, Gemini Enterprise Agent Platform, Google GenAI에는 지원되지 않습니다(이들은 네이티브 클라우드 ID로 인증). 토글은 LangServe (Deprecated) 사전 설정에도 숨겨집니다.

모델 구성에서 OAuth 구성

OAuth 구성에는 Workspace Admin 역할 또는 workspaces:manage-model-configs 권한이 있는 커스텀 역할이 필요합니다. 권한이 없는 구성원은 마스킹된 시크릿 힌트와 함께 OAuth 필드가 비활성화된 것을 봅니다. LangSmith UI에서:

Settings > Model configurations로 이동해 + Create를 클릭하거나 오버플로우 메뉴 > Edit로 기존 행을 엽니다.
호환 프로바이더를 선택하고 평소처럼 모델 파라미터를 구성합니다.
Use Custom OAuth를 켭니다.
OAuth 필드를 채웁니다:
- Token URL: IdP 토큰 엔드포인트, 예: https://login.example.com/oauth/token.
- Client ID: OAuth 클라이언트 식별자.
- Client Secret: OAuth 클라이언트 시크릿. 저장 시 암호화됩니다.
- Token Endpoint Auth Method: client_secret_basic 또는 client_secret_post.
- Extra parameters: 토큰 요청 본문으로 보내는 키/값 행. scope, audience, resource 또는 IdP가 기대하는 다른 파라미터에 사용합니다. 여러 scope를 보낼 때는 값당 한 행을 추가합니다. 중복 키는 다중 값 쌍으로 보내집니다.
- Extra headers: 토큰 요청과 함께 보내는 추가 헤더. Authorization 같은 예약 헤더는 저장 시 거부됩니다.
Save를 클릭합니다.

편집 의미론

OAuth 필드는 저장된 시크릿을 보호하는 편집 동작을 따릅니다:

시크릿 라운드트립: 서버는 시크릿을 ********로 반환합니다. 입력은 "Secret is set. Type to replace." 힌트와 함께 빈 상태로 렌더링됩니다. 다시 입력하지 않고 제출하면 저장된 시크릿은 변경되지 않습니다.
끄면 자격 증명 보존: Use Custom OAuth를 끄면 OAuth 플로우가 비활성화되지만 저장된 필드는 유지됩니다. 다시 켜면 동일한 자격 증명을 계속 사용합니다.
필드 지우기: 구성을 편집하고 필드를 비워 명시적으로 지웁니다.
Save as preset으로 복제: 일회성 구성을 새 사전 설정으로 저장할 때 비시크릿 OAuth 필드는 새 행으로 복사됩니다. 시크릿은 읽기에 노출되지 않으므로 전송할 수 없어, 복제본에서 OAuth는 시크릿을 다시 입력할 때까지 강제로 비활성화됩니다.

요청 흐름

요청이 OAuth 활성 구성에 대해 실행되면 LangSmith는 내부 브로커를 통해 bearer를 발급하고 결과를 캐시하며, 캐시된 토큰이 만료될 때까지 모든 발신 LLM 호출에 bearer를 찍습니다.

폴백 동작

브로커가 토큰을 발급할 수 없으면(IdP 도달 불가, 자격 증명 무효, 요청 준비와 실행 사이 구성 삭제) 요청은 해당 프로바이더의 정적 워크스페이스 API 키로 폴백합니다. 워크스페이스 키가 없으면 발신 호출에서 프로바이더 401이 예상됩니다.

토큰 회전은 캐시된 bearer가 만료된 후에만 전파됩니다. IdP에서 구성한 access token TTL에 맞춰 회전을 계획하세요.

표면 커버리지

OAuth 활성 구성은 모델 구성이 소비되는 모든 곳에서 인정됩니다:

Playground: 채팅 실행과 실험 실행.
Evaluators: LLM-as-judge 구성, Reuse, Preview Test, Evaluator Details Test는 모든 프롬프트가 OAuth 활성 구성으로 해석될 때 워크스페이스 시크릿 프롬프트를 건너뜁니다.
Insights: Thinking과 Summarization 구성이 독립적으로 해석됩니다.
Chat
Fleet

구성에서 OAuth를 활성화하면 LangSmith는 해당 구성에 대해 워크스페이스 시크릿을 묻지 않습니다. 브로커가 요청 시점에 자격 증명을 제공하기 때문입니다.

보안과 감사

저장 시 암호화: 클라이언트 시크릿은 워크스페이스 시크릿에 사용되는 것과 동일한 파생으로 Fernet 암호화됩니다.
Bearer 캐싱: access token은 만료까지 캐시되며 로그에 절대 기록되지 않습니다.

FAQ

단일 OAuth 자격 증명 세트를 워크스페이스 간에 공유할 수 있나요? 아니요. OAuth 자격 증명은 워크스페이스 범위인 모델 구성에 저장됩니다. 자격 증명이 같은 IdP 클라이언트를 가리켜도 각 워크스페이스는 자체 자격 증명을 입력합니다.

OAuth 활성 구성이 갑자기 정적 워크스페이스 키를 사용하는 이유는? 브로커가 bearer를 발급할 수 없으면(IdP 도달 불가, 자격 증명 무효, 요청 준비와 실행 사이 구성 삭제) 요청은 해당 프로바이더의 정적 워크스페이스 API 키로 폴백합니다. 모델 구성을 다시 열어 Token URL이 도달 가능한지, Client ID와 시크릿이 최신인지, Token Endpoint Auth Method가 IdP가 기대하는 것과 일치하는지 확인하세요.

클라이언트 시크릿을 어떻게 회전하나요? 모델 구성을 편집하고 Client Secret 필드에 시크릿을 다시 입력합니다. 이전 시크릿은 저장 시 덮어씁니다. Redis 캐시된 bearer는 TTL이 만료될 때까지 계속 동작하며, 이후 브로커는 회전된 시크릿으로 새 bearer를 발급합니다.

OAuth와 LLM auth proxy를 함께 사용할 수 있나요? 네. 라우팅은 구성별입니다. OAuth가 활성화된 구성은 OAuth를 사용하고, 그렇지 않은 구성은 조직 수준에서 프록시가 활성화되어 있으면 LLM auth proxy로 넘어갑니다. 단일 다중 모델 작업이 두 흐름을 혼합할 수 있습니다.

더 알아보기

프롬프트 설정 구성 — Playground 설정.
LLM auth proxy 셀프 호스팅 — 프록시 라우팅.