Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Permissões e Limites das Coleções

Aula 8 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. O risco específico das bases de conhecimento
  2. Duas chaves, duas funções
  3. A permissão AddFileToCollection
  4. Quotas e os seus custos
  5. Isolar, rodar, monitorizar
  6. Um ficheiro, múltiplas coleções
  7. Pontos-chave

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:

ChaveUtilizaçãoÂmbito
XAI_API_KEYCarregamento de ficheiros e pesquisaOperações de leitura e utilização
XAI_MANAGEMENT_API_KEYGestão de coleçõesOperaçõ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:

  1. Iniciar sessão na consola da xAI
  2. Criar uma nova Chave de API de Gestão
  3. Ativar a permissão AddFileToCollection
  4. 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