BYOK · 자체 LLM Key 사용

BYOK(Bring Your Own Key)는 LLM 토큰 청구에 대한 Braidrun의 핵심 개념입니다. OpenAI/Anthropic/DeepSeek/Kimi/OpenRouter 등에서 얻은 API 키를 유지하면 Braidrun가 가격 인상 없이 이를 조정할 수 있도록 도와드립니다.

왜 BYOK인가?

• 투명한 청구 — 토큰 소비는 귀하의 LLM 계정에 직접 기록되며 Braidrun는 가격을 이전하거나 인상하지 않습니다.
• 모델의 자유 — 플랫폼의 통합 패키지에 제한을 받지 않고 자신의 계정의 Claude Opus, GPT-5 및 모든 OpenRouter 라우팅 소형 모델을 사용할 수 있습니다.
• 할당량 및 현재 한도를 제어할 수 있습니다. — 더 높은 TPM이 필요하십니까? OpenAI로 이동하여 Tier로 업그레이드하세요. 플랫폼을 다룰 필요가 없습니다.
• 안전하고 제어 가능 — 키는 OpenAI 콘솔에서 언제든지 취소할 수 있으며 전체 링크에 대한 최종 결정권은 귀하에게 있습니다.

지원되는 제공업체

• OpenAI — GPT-4.1 / 4.1-mini / GPT-5 / o1 / o3
• Anthropic — Claude Opus 4 / Sonnet 4 / Haiku 4
• Claude Code — Anthropic API 키 또는 Claude 구독 토큰(자격 증명 provider=claude_code_oauth)
• Codex — OpenAI API 키 또는 Codex 구독 auth.json(자격 증명 provider=codex_subscription)
• DeepSeek — DeepSeek-V3.5 / DeepSeek-Reasoning
• Kimi — Kimi K2 / 128K context
• OpenRouter — OpenRouter를 통해 지원되는 모델(Mistral / Llama / Gemini 등)로 라우팅
• 내부 LLM(Enterprise 버전은 자체 호스팅 vLLM/TGI/Ollama 엔드포인트에 액세스할 수 있음)

1단계: 제공업체로 이동하여 키 받기

2단계: 자격 증명 센터에 저장

1. 왼쪽의 "자격증명 관리" → "새 자격증명".
2. 명명 제안:
   • openai_main / openai_prod / openai_test
   • anthropic_team_budget / anthropic_personal
   • deepseek_production
3. 유형: api_key; 값: 공급자가 제공한 키를 붙여넣습니다. 네임스페이스: 개인 또는 팀(혼자서 사용하는지, 여러 사람과 공유하는지에 따라 다름)
4. 저장합니다. 플랫폼 암호화 및 저장.

3단계: 공급자를 에이전트에 바인딩

agents:
  writer:
    preset: writer
    overrides:
      model: claude-opus-4-7
      provider: anthropic_team_budget    # ← 凭据中心的凭据名

AI Assistant: 현재 계정 구성

앱 내 AI 어시스턴트는 더 이상 관리자 중앙 설정에 의존하지 않습니다. 계정 설정 → AI 어시스턴트에서 모델 provider를 선택하거나 Claude Code / Codex 영역에서 API Key / 구독 한도 모드를 선택하세요. 저장 내용은 현재 계정에만 적용됩니다.

4단계(선택 사항): 공급자 세부 정보 구성

일부 공급자는 api_base, 조직 ID, 사용자 정의 헤더 등 추가 구성이 필요합니다. "자격 증명 관리 → 공급자 구성"에서 확장합니다.

# 凭据中心 → Provider 配置
# 类型: OpenAI
api_base: https://api.openai.com/v1   # 或你的代理 / Azure endpoint
organization: org_xxxxx                 # 分账 organization
default_headers:
  OpenAI-Beta: assistants=v2

다중 키 원장 공유

시나리오: 부서별로 계정을 유지하려고 하거나 개발/프로덕션을 위한 두 개의 키 세트가 있습니다.

1. 자격 증명 센터에서 각 키에는 독립적인 이름(openai_marketing / openai_engineering)이 있습니다.
2. 서로 다른 워크플로의 에이전트는 서로 다른 공급자에 바인딩됩니다.
3. OpenAI 측에서는 토큰 소비를 추적하기 위해 프로젝트를 여러 프로젝트로 나누고, 각 프로젝트의 청구서는 자연스럽게 분리됩니다.

비용 추적

청구서가 공급자 측에 있더라도 Braidrun는 여전히 토큰을 추적하고 모델의 현재 가격에서 변환된 예상 비용을 추적합니다.

• 각 실행의 상단 요약에는 토큰 + 예상 비용이 표시됩니다.
• "데이터 대시보드" 페이지는 일/주/월별로 집계됩니다.
• "단일 실행 비용이 X를 초과하면 알람"을 설정할 수 있습니다.

Braidrun의 추정치는 공공 공급자 가격표를 기반으로 합니다. 할인(OpenAI Enterprise/DeepSeek 분기별 계약)을 활용하는 경우 실제 청구서는 추정치보다 낮습니다.

전류 제한 및 재시도

키에는 TPM(분당 토큰 수) 상한이 있습니다. 플랫폼에는 세 가지 보호 계층이 있습니다.

1. 공급자 현재 제한(429를 초과하는 경우 공급자 측에서는 엄격함)
2. Braidrun 내부 TPM 소프트 제한(일회성 폭발 방지)
3. 단계 수준 재시도.backoff(일시적 429 자동 백오프 재시도)

키 순환

1. 공급자 측에서 새 키를 만듭니다(이전 키를 취소하지 마세요).
2. Braidrun 자격 증명 센터 → 해당 자격 증명 찾기 → "업데이트 값"에 새 키를 붙여 넣습니다.
3. 1시간 동안 기다립니다(이전 키를 사용하여 실행 중인 실행이 완료될 때까지).
4. 모든 것이 정상인지 확인하고 공급자 측으로 이동하여 이전 키를 취소합니다.

장애 조치/대체

공급자가 가끔 불안해지면 에이전트에서 폴백을 구성할 수 있습니다.

agents:
  writer:
    preset: writer
    overrides:
      model: claude-opus-4-7
      provider: anthropic_main
      fallback:
        model: gpt-4.1
        provider: openai_main

기본 공급자가 5xx / 속도 제한을 반환하면 폴백이 자동으로 전환됩니다.

FAQ

Braidrun에서 내 키 값을 볼 수 있나요?

런타임 플랫폼 서비스는 일반 텍스트 키를 사용하여 공급자를 호출해야 합니다. 이 순간은 기술적으로 표시됩니다. 하지만:

• 데이터베이스 삭제 시 AES-256-GCM 암호화가 사용되며 DB 덤프에서는 일반 텍스트를 볼 수 없습니다.
• 런타임 암호 해독은 단일 단계의 컨텍스트에서만 적용되며 로그를 입력하거나 스냅샷을 작성하거나 다른 단계로 흘러가지 않습니다.
• Enterprise 버전은 HSM/KMS 통합을 지원하며, 키 암호 해독은 관리형 KMS에서 수행됩니다.

플랫폼 크레딧과 BYOK를 혼합할 수 있나요?

그렇습니다. 에이전트에 공급자가 없으면 플랫폼의 통합 키를 사용합니다(플랫폼 할당량 사용). 공급자가 장착되어 있으면 키를 사용합니다. 동일한 워크플로에서 다양한 단계를 혼합할 수 있습니다.

다음 단계

• 자격 증명 — 자세한 내용은 자격 증명 센터
• Agent 구성에 대한 자세한 설명 — 공급자와 함께 사용되는 재정의 필드