Permissões e Limites das Coleções
Nesta página
O risco específico das bases de conhecimento
Uma base de conhecimento empresarial nunca é trivial: notas internas, relatórios confidenciais, contratos em negociação. Se os controlos de acesso falharem, não vaza apenas um ficheiro isolado; expõe a base inteira, completa com um motor de busca para encontrar o que importa. O sistema de permissões da xAI mitiga este risco ao separar direitos, enquanto as quotas governam a utilização e a faturação.
Duas chaves, duas funções
O ecossistema xAI baseia-se em duas credenciais para âmbitos distintos:
| Chave | Utilização | Âmbito |
|---|---|---|
XAI_API_KEY | Carregamento de ficheiros e pesquisa | Operações de leitura e utilização |
XAI_MANAGEMENT_API_KEY | Gestão de coleções | Operações de administração |
Esta separação aplica concretamente o princípio do privilégio mínimo. Um programador que ligue um chatbot de suporte à sua base precisa de consultar a coleção, nunca de a apagar. Ao fornecer-lhe apenas a chave padrão, um erro de script ou uma chave comprometida não pode destruir um índice construído ao longo de meses.
A permissão AddFileToCollection
Uma Chave de API de Gestão não é todo-poderosa por defeito. Os seus direitos são explícitos e o mais crítico para as coleções é AddFileToCollection. Sem ela, pode criar e listar coleções, mas não consegue adicionar um único documento — uma situação confusa, pois tudo parece funcionar até à ingestão. Gerar uma chave correta envolve quatro passos:
- Iniciar sessão na consola da xAI
- Criar uma nova Chave de API de Gestão
- Ativar a permissão
AddFileToCollection - Armazenar a chave em segurança: variável de ambiente ou gestor de segredos
Quando a permissão falta, a API é explícita e devolve um erro 403:
{
"error": {
"message": "Insufficient permissions",
"type": "permission_error",
"code": 403
}
}
O seu primeiro passo deve ser verificar os direitos da chave na consola, em vez de suspeitar do pedido, cuja sintaxe nada tem a ver com a rejeição.
Quotas e os seus custos
Três limites governam o armazenamento por conta: 100.000 ficheiros no total, 100 GB de capacidade cumulativa e 100 MB por ficheiro individual nas coleções — mais do dobro dos 48 MB permitidos apenas pela API de Ficheiros, permitindo-lhe incluir documentos que não poderia enviar como anexos diretos.
No lado da faturação, destacam-se duas rubricas: a Pesquisa em Coleções é faturada a 2,50 $ por 1.000 chamadas de pesquisa, enquanto os Anexos de Ficheiros custam 10 $ por 1.000 chamadas. A diferença é significativa e pesa nas escolhas arquiteturais. Sob utilização intensiva, consultar uma coleção indexada custa significativamente menos do que reanexar o mesmo documento a cada pergunta.
Se as suas necessidades excederem estas quotas, o suporte da xAI pode conceder um aumento. Prepare o seu pedido com números concretos — contagem alvo de ficheiros, volume total, frequência de pesquisa esperada — em vez de uma estimativa vaga. Isto acelera o processamento do pedido.
Isolar, rodar, monitorizar
A primeira prática diz respeito às chaves. Atribua chaves diferentes a cada ambiente, para que um script de desenvolvimento nunca possa tocar na base de produção. Nunca forneça uma chave de Gestão a um serviço cuja única necessidade seja a pesquisa. E rode estas chaves regularmente, especialmente após a saída de um colaborador com acesso aos segredos.
A segunda diz respeito à estrutura. Em vez de uma única coleção onde coexistem documentação pública e contratos, separe as suas bases por nível de confidencialidade: uma base «pública» para documentação aberta, uma base «interna» para documentos da empresa e uma base «confidencial» para dados sensíveis. Cada serviço recebe então apenas o acesso de que necessita, e a pergunta «pode este chatbot citar um contrato?» fica respondida por conceção.
A terceira é a monitorização. Verifique o seu consumo na consola da xAI, defina um alerta para qualquer aumento inesperado no volume de pesquisa — muitas vezes o primeiro sinal de um ciclo descontrolado — e mantenha um registo escrito de quais os serviços que acedem a quais coleções.
Um ficheiro, múltiplas coleções
Este isolamento não exige a duplicação dos seus documentos, uma vez que o mesmo ficheiro pode pertencer a várias coleções. Um relatório técnico surge assim em «product-documentation» para a equipa técnica, em «quarterly-reports» para a gestão e em «support-base» para o serviço de apoio ao cliente. É armazenado apenas uma vez, conta apenas uma vez para as suas quotas e permanece pesquisável nos três contextos — vistas temáticas por público, sem cópias divergentes.
Pontos-chave
- Duas chaves de API distintas: padrão para utilização, Gestão para administração
- A permissão
AddFileToCollectioné essencial para povoar as coleções - Os limites são 100.000 ficheiros, 100 GB e 100 MB por ficheiro
- Separe as suas coleções por nível de confidencialidade
- Um ficheiro pode pertencer a várias coleções sem duplicação