모델 구성 관리하기

모델 구성 관리하기 (Manage model configurations)

모델 구성을 관리하고 LangSmith 기능 전반에서 그 가용성을 제어해요.

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

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

구성은 OAuth 클라이언트 자격 증명도 담을 수 있어서, LangSmith는 정적 API 키 대신 요청 시점에 여러분의 IdP에 대해 단기 유효 베어러 토큰을 발행해요.

기능 접근 (Feature Access)

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

기능	모델 선택 경험
Playground	전체 모델 제어 — 모든 파라미터 보기·조정. 내장 모델 없음; 워크스페이스 구성에 의존.
Evaluators	전체 모델 제어 — 모든 파라미터 보기·조정. 내장 모델 없음; 워크스페이스 구성에 의존.
Fleet	기본적으로 정리된 목록에서 선택. 커스텀 워크스페이스 구성도 추가할 수 있음.
Chat	기본적으로 정리된 목록에서 선택. 커스텀 워크스페이스 구성도 추가할 수 있음.
Insights (Thinking)	심층 분석에 사용하는 모델. 기본적으로 프로바이더 추천이 있는 정리된 목록에서 선택. 커스텀 워크스페이스 구성도 추가할 수 있음.
Insights (Summarization)	가벼운 요약에 사용하는 모델. 기본적으로 프로바이더 추천이 있는 정리된 목록에서 선택. 커스텀 워크스페이스 구성도 추가할 수 있음.

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

참고: Insights는 분석용과 요약용 두 개의 별도 행을 사용해요. UI는 어느 행에든 호환되지 않는 프로바이더나 권장되지 않는 모델을 선택하면 경고를 표시해요.

기능 접근 구성하기 (Configure feature access)

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

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

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

조직 전역 프로바이더 제어 (Organization-wide provider control)

프로바이더 가용성은 두 수준에서 제어돼요:

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

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

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

조직에 대해 프로바이더 비활성화하기 (Disable a provider for the organization)

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

조직 범위 모델 구성 (Organization-scoped model configurations)

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

조직 관리자는 조직 수준에서 모델 구성을 만들 수 있어서, 단일 구성이 워크스페이스별로 중복하지 않고 조직의 모든 워크스페이스에서 사용할 수 있어요.

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

조직 범위 구성 만들기 (Create an organization-scoped configuration)

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

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

워크스페이스에서 조직 범위 구성 활성화하기 (Enable an org-scoped configuration in a workspace)

조직 범위 구성이 생성된 후 워크스페이스 관리자가 워크스페이스 기능에 나타나기 전에 활성화해야 해요:

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

제한사항 (Limitations)

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

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

구성 (Configurations)

Configurations 테이블은 워크스페이스의 이름 있는 모델 구성의 공유 라이브러리예요. LangSmith에서 만든 구성(Playground 포함)이 여기에 나타나며 모든 기능에 걸쳐 재사용할 수 있어요.

구성 만들기 (Create a configuration)

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

구성 편집하기 (Edit a configuration)

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

구성 삭제하기 (Delete a configuration)

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

OAuth 클라이언트 자격 증명 (OAuth client credentials)

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

모델 구성이 OAuth2 게이트웨이 뒤에 있을 때, 정적 API 키를 배포하는 대신 구성에 직접 OAuth client_credentials를 저장할 수 있어요. LangSmith는 요청 시점에 그 자격 증명을 단기 유효 베어러 토큰으로 교환하고, 아웃바운드 LLM 호출에 Authorization: Bearer <token>으로 첨부하며, 토큰이 만료되기 전에 갱신해요. 이는 워크스페이스를 LLM 인증 프록시로 라우팅하는 것에 대한 구성별 셀프서비스 대안이에요; 둘은 구성별로 상호 배타적이에요.

OAuth 클라이언트 자격 증명은 커스텀 모델 구성을 지원하는 모든 플랜에서 사용할 수 있어요. Use Custom OAuth 토글은 베어러 토큰 프로바이더(OpenAI, Anthropic, OpenAI 호환 엔드포인트 등)에 적용되며, 네이티브 클라우드 아이덴티티로 인증하는 Bedrock, Gemini Enterprise Agent Platform, Google GenAI에는 지원되지 않아요. 토글은 LangServe (Deprecated) 프리셋에도 숨겨져 있어요.

모델 구성에서 OAuth 구성하기 (Configure OAuth on a model configuration)

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를 클릭해요.

편집 의미 (Edit semantics)

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

시크릿 왕복: 서버는 시크릿을 ********로 반환해요. 입력은 "Secret is set. Type to replace." 힌트와 함께 빈 상태로 렌더링돼요. 다시 입력하지 않고 제출하면 저장된 시크릿이 변경되지 않아요.
토글 끄기 시 자격 증명 유지: Use Custom OAuth를 끄면 OAuth 흐름이 비활성화되지만 저장된 필드는 유지돼요. 다시 켜면 동일한 자격 증명 사용을 재개해요.
필드 지우기: 구성을 편집하고 필드를 비워 명시적으로 지워요.
Save as preset으로 복제: 일회성 구성을 새 프리셋으로 저장하면 비시크릿 OAuth 필드가 새 행에 복사돼요. 시크릿은 읽기용으로 노출되지 않으므로 전송할 수 없어서, 시크릿을 다시 입력할 때까지 복제본에서 OAuth가 강제로 비활성화돼요.

요청 흐름 (How a request flows)

OAuth 활성 구성에 대해 요청이 실행되면 LangSmith는 내부 브로커를 통해 베어러를 발행하고, 결과를 캐시하며, 캐시된 토큰이 만료될 때까지 모든 아웃바운드 LLM 호출에 베어러를 첨부해요.

sequenceDiagram
    autonumber
    participant Caller as LangSmith service<br/>(Playground, Evals, Insights, Chat, Fleet)
    participant Broker as Token broker
    participant Cache as Redis cache
    participant IdP as Customer IdP
    participant LLM as Upstream LLM provider
    Caller->>Broker: Mint token for configuration X
    Broker->>Cache: Lookup cached token for X
    alt Cache hit
        Cache-->>Broker: Cached token
    else Cache miss or expired
        Broker->>IdP: client_credentials grant
        IdP-->>Broker: access_token + expires_in
        Broker->>Cache: Store until expiry
    end
    Broker-->>Caller: access_token
    Caller->>LLM: Request with Authorization: Bearer <token>
    LLM-->>Caller: Response

OAuth와 LLM 인증 프록시 간 라우팅은 조직별이 아니라 구성별로 이뤄져요. 각 요청은 구성의 OAuth 상태에 따라 OAuth 또는 LLM 인증 프록시로 해석돼요. 단일 멀티모델 작업(예: Thinking과 Summarization 모델이 분리된 Insights)은 각 모델이 독립적으로 해석되므로 두 흐름을 혼합할 수 있어요.

폴백 동작 (Fallback behavior)

브로커가 토큰을 발행할 수 없으면(IdP 접근 불가, 자격 증명 무효, 요청 준비와 실행 사이에 구성 삭제) 요청은 프로바이더의 정적 워크스페이스 API 키로 폴백돼요. 워크스페이스 키가 설정되지 않았다면 아웃바운드 호출에서 프로바이더 401을 기대하세요.

토큰 회전은 캐시된 베어러가 만료된 후에만 전파돼요. IdP에서 구성된 액세스 토큰 TTL을 기준으로 회전을 계획하세요.

표면 범위 (Surface coverage)

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

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

구성에 OAuth가 활성화되면 LangSmith는 해당 구성에 대해 워크스페이스 시크릿을 요청하지 않아요. 브로커가 요청 시점에 자격 증명을 공급하기 때문이에요.

보안 및 감사 (Security and audit)

저장 시 암호화: 클라이언트 시크릿은 워크스페이스 시크릿에 사용된 것과 동일한 파생으로 Fernet 암호화돼요.
베어러 캐싱: 액세스 토큰은 만료까지 캐시되며 로그에 기록되지 않아요.

FAQ

단일 OAuth 자격 증명 세트를 워크스페이스 간에 공유할 수 있나요? (Can a single set of OAuth credentials be shared across workspaces?)

아니요. OAuth 자격 증명은 워크스페이스 범위인 모델 구성에 저장돼요. 각 워크스페이스는 자체 자격 증명을 입력하며, 자격 증명이 동일한 IdP 클라이언트를 가리켜도 그래요.

OAuth 활성 구성이 갑자기 정적 워크스페이스 키를 사용하는 이유는 무엇인가요? (Why is my OAuth-enabled configuration suddenly using a static workspace key?)

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

클라이언트 시크릿을 어떻게 회전하나요? (How do I rotate the client secret?)

모델 구성을 편집하고 Client Secret 필드에 시크릿을 다시 입력해요. 저장 시 이전 시크릿이 덮어써져요. Redis 캐시된 베어러는 TTL이 만료될 때까지 계속 동작하며, 그 후 브로커는 회전된 시크릿을 사용해 새 베어러를 발행해요.

OAuth와 LLM 인증 프록시를 함께 사용할 수 있나요? (Can OAuth and the LLM auth proxy be used together?)

예. 라우팅은 구성별이에요. OAuth가 활성화된 구성은 OAuth를 사용해요; 그렇지 않은 구성은 프록시가 조직 수준에서 활성화되었을 때 LLM 인증 프록시로 폴백해요. 단일 멀티모델 작업은 두 흐름을 혼합할 수 있어요.

출처: 문서

모델 구성 관리하기