Organizações e Espaços de Trabalho
Nesta página
Estrutura da sua equipa no AI Studio
Enquanto trabalha sozinho, uma única chave de API é suficiente. Os problemas começam no momento em que três programadores partilham a mesma conta: ninguém sabe qual chave alimenta qual aplicação, a fatura chega como um bloco indecifrável e, no dia em que alguém deixa a equipa, tem de revogar tudo. O AI Studio resolve isto com uma arquitetura de dois níveis: Organizações e Espaços de Trabalho. Compreender esta estrutura é essencial para gerir a faturação, as permissões e o isolamento de recursos.
O modelo Organização / Espaço de Trabalho
A Organização situa-se no topo da hierarquia. É criada automaticamente quando se regista e representa a sua entidade — empresa, equipa ou departamento. É aqui que tudo se consolida: a faturação, que agrega todos os custos; a seleção do nível de subscrição (Experiment, Scale ou Enterprise); os limites de utilização, ou seja, as quotas globais de tokens e pedidos; e a alocação de membros, incluindo convites e gestão de lugares. Criar uma nova organização requer apenas um nome e a aceitação dos termos de serviço, e nada impede que um único utilizador pertença a várias organizações em simultâneo.
Os Espaços de Trabalho são subconjuntos dentro de uma Organização, concebidos para segmentar o acesso e os custos por projeto, equipa ou ambiente. Cada espaço de trabalho isola as suas chaves de API, que concedem acesso apenas aos seus próprios recursos, e partilha modelos ajustados (fine-tuned) e conjuntos de dados de treino entre os seus membros. O consumo permanece rastreável espaço de trabalho por espaço de trabalho, pelo que pode dizer exatamente quanto custa o chatbot de suporte em comparação com o motor de busca interno.
Gestão de funções e permissões
Três funções coexistem ao nível da Organização, com âmbitos deliberadamente distintos.
| Função | Faturação | Membros | Espaços de Trabalho | Chaves de API |
|---|---|---|---|---|
| Proprietário (Owner) | Sim | Sim | Sim | Sim |
| Administrador (Admin) | Não | Sim | Sim | Sim |
| Membro (Member) | Não | Não | Limitado | Sim |
Lembre-se da linha do meio: um Administrador gere equipas e espaços de trabalho, mas nunca toca na faturação. Isto permite-lhe entregar a administração técnica a um responsável de ML sem lhe dar acesso ao cartão de crédito da empresa.
Criar um espaço de trabalho requer, portanto, permissões de Administrador. A partir da página Admin da sua organização:
- Aceda à secção Workspaces
- Clique em Create Workspace
- Atribua-lhe um nome descritivo (por exemplo:
production,staging,research) - Configure as permissões iniciais
Adicionar um colaborador segue uma lógica semelhante:
- Aceda a Admin > Members
- Clique em Invite
- Introduza o endereço de e-mail do colaborador
- Atribua uma função (Admin, Member)
- Selecione os espaços de trabalho aos quais terá acesso
Melhores práticas organizacionais
A primeira regra é separar os ambientes. Crie pelo menos dois espaços de trabalho, idealmente três, para isolar o que acontece em desenvolvimento do que toca nos seus utilizadores.
Organization "MaStartup"
├── Workspace "development" → chaves de API de dev, quotas reduzidas
├── Workspace "staging" → testes de integração
└── Workspace "production" → chaves de API de prod, quotas elevadas
Esta separação impede que um ciclo infinito escrito numa sexta-feira à noite em desenvolvimento devore as quotas de produção e torna a monitorização de custos por ambiente imediatamente legível.
Em seguida, vem a rotação de chaves. Como cada chave está ligada a um espaço de trabalho, substituir uma sem interromper o serviço requer uma ordem específica: gere a nova chave no espaço de trabalho relevante, implemente-a na sua aplicação, verifique se os pedidos realmente funcionam com ela e só então elimine a antiga. Inverter os dois últimos passos garante uma interrupção de serviço.
import os
# Melhores práticas: chave de API via variável de ambiente
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Uma chave codificada diretamente no código-fonte acabará sempre num repositório Git, depois no histórico desse repositório, onde sobreviverá a todas as suas tentativas de limpeza. Utilize uma variável de ambiente desde a primeira linha.
Nas grandes organizações, a governança beneficia também de ter um espaço de trabalho por equipa funcional — ciência de dados, backend, produto — além de um espaço de trabalho dedicado ao ajuste fino (fine-tuning) que centraliza os conjuntos de dados em vez de os deixar duplicar. Nomes explícitos de espaços de trabalho tornam os relatórios mensais muito mais fáceis.
Cenário concreto: configuração
Vamos pegar numa empresa de quinze pessoas que adota o Mistral. O CTO cria a Organização e subscreve o nível Scale, abrindo depois três espaços de trabalho: dev, staging e prod. Os programadores recebem acesso de Membro limitado ao espaço de trabalho dev, enquanto o responsável de ML obtém acesso de Administrador aos três. Cada espaço de trabalho tem as suas próprias chaves de API, isoladas umas das outras, pelo que uma chave de desenvolvimento comprometida não coloca em risco nada na produção.
O painel de administração, acessível em admin.mistral.ai, exibe então o consumo por espaço de trabalho. Esta é a tabela que o CTO abrirá no final do mês para atribuir custos por projeto, sem ter de instrumentar nada no código.
Pontos-chave
- A Organização é o nível para faturação e gestão global
- Os Espaços de Trabalho isolam chaves de API, modelos ajustados e custos
- Separe sempre desenvolvimento, staging e produção em espaços de trabalho distintos
- Armazene as chaves de API em variáveis de ambiente, nunca no código
- O painel de administração permite-lhe acompanhar o consumo por espaço de trabalho em tempo real