BYOK · traga sua própria chave LLM

BYOK (Bring Your Own Key) é o conceito central do Braidrun para faturamento de token LLM: você mantém a chave API obtida do OpenAI / Anthropic / DeepSeek / Kimi / OpenRouter, etc., e o Braidrun o ajudará a ajustá-lo sem aumentar o preço.

Por que BYOK

• Faturamento transparente — O consumo de tokens é registrado diretamente em sua própria conta LLM e a Braidrun não transfere nem aumenta preços.
• Liberdade de modelo — Você pode usar o Claude Opus da sua própria conta, GPT-5 e qualquer modelo pequeno de roteamento OpenRouter - sem ser restringido pelo pacote unificado da plataforma.
• A cota e o limite atual estão sob seu controle — Precisa de TPM mais alto? Basta ir ao OpenAI e fazer upgrade para Tier. Não precisa lidar com a plataforma.
• Seguro e controlável — A chave pode ser revogada no console OpenAI a qualquer momento, e você tem a palavra final sobre todo o link.

Provedores Suportados

• OpenAI — GPT-4.1 / 4.1-mini / GPT-5 / o1 / o3
• Anthropic — Claude Opus 4 / Sonnet 4 / Haiku 4
• Claude Code — Tecla de API antrópica ou Token de assinatura Claude (fornecedor credencial=claude code oauth)
• Codex — OpenAI API Key ou Codex Subscription auth.json (Credentials provider=codex subscription)
• DeepSeek — DeepSeek-V3.5 / DeepSeek-Reasoning
• Kimi — Kimi K2 / 128K context
• OpenRouter — Roteamento via OpenRouter para qualquer um de seus modelos suportados (Mistral/Llama/Gemini etc.)
• LLM interno (a versão Enterprise pode acessar o endpoint vLLM/TGI/Ollama auto-hospedado)

Etapa 1: vá ao provedor para obter a chave

Etapa 2: Salvar na Central de Credenciais

1. "Gerenciamento de credenciais" à esquerda â "Nova credencial".
2. Sugestões de nomenclatura:
   • openai_main / openai_prod / openai_test
   • anthropic_team_budget / anthropic_personal
   • deepseek_production
3. Tipo: api_key;
4. Salvar.

Etapa 3: vincular o provedor ao agente

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

Assistente de IA: Configurar a conta corrente

O assistente de IA no aplicativo não depende mais da configuração de administrador centralizada. Acesse Configurações da Conta → Assistente de IA para escolher o fornecedor do modelo, ou escolha o modo chave de API / assinatura-quota na seção Código Claude / Codex. A poupança afecta apenas a conta corrente.

Etapa 4 (opcional): Configurar detalhes do provedor

Alguns provedores exigem mais configuração – api_base, ID da organização, cabeçalhos personalizados.

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

Compartilhamento de razão multichave

Cenário: Você deseja manter contas por departamento ou possui dois conjuntos de chaves para desenvolvimento/produção.

1. Na central de credenciais, cada Chave possui um nome independente (openai_marketing / openai_engineering).
2. Agentes de diferentes workflows estão vinculados a diferentes provedores.
3. Do lado do OpenAI, os projetos são divididos em projetos para rastrear o consumo de tokens, e as contas de cada projeto são naturalmente separadas.

Rastreamento de custos

Mesmo que a fatura esteja do lado do Provedor, o Braidrun ainda rastreia o token e o custo estimado convertido do preço atual do modelo:

• O resumo superior de cada execução mostra tokens + custo estimado
• A página "Painel de dados" agrega por dia/semana/mês
• Você pode definir "Alarme quando o custo de execução única exceder X"

Observe que as estimativas da Braidrun são baseadas na lista de preços do provedor público – se você aproveitar os descontos (contrato trimestral OpenAI Enterprise / DeepSeek), a conta real será menor que a estimativa.

Limitação atual e nova tentativa

Sua chave tem um limite máximo de TPM (Tokens por minuto).

1. Limite atual do provedor (difícil para o provedor, se exceder 429)
2. Limite suave TPM interno do Braidrun (para evitar explosão única)
3. retry.backoff em nível de etapa (nova tentativa de espera automática transitória 429)

Rotação de chave

1. Crie uma nova chave no lado do provedor (não revogue a antiga).
2. Braidrun Credential Center â Encontre a credencial correspondente â Cole a nova chave em "Atualizar valor".
3. Aguarde 1 hora (para deixar a execução em execução com a chave antiga terminar).
4. Confirme se está tudo normal, vá até o lado do Provedor para revogar a chave antiga.

Failover / Retomada

Quando o Provedor ocasionalmente treme, você pode configurar o fallback no Agente:

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

O fallback é alterado automaticamente quando o Provedor principal retorna 5xx/limite de taxa.

FAQ

O Braidrun pode ver meu valor-chave?

O serviço de plataforma de execução precisa usar a chave de texto clara para chamar o Provedor - este momento é tecnicamente visível. Mas:

• A criptografia AES-256-GCM é usada ao eliminar o banco de dados e o texto simples não pode ser visto no dump do banco de dados;
• A descriptografia em tempo de execução só entra em vigor no contexto de uma única etapa e não insere logs, grava instantâneos ou flui para outras etapas;
• A versão empresarial suporta integração HSM/KMS, a descriptografia da chave é feita no KMS gerenciado.

Posso misturar crédito de plataforma + BYOK?

Sim.

Próximo passo

• Credenciais — Centro de Credenciais para mais detalhes
• Guia de Configuração do Agente — Quais campos de substituição são usados com o provedor