Criar e gerir coleções
Nesta página
De ficheiros isolados a uma base de conhecimento
Até agora, cada documento existia isoladamente: carregava-o, referenciava-o e o índice criado para a ocasião desaparecia com o pedido. As coleções mudam a escala: agrupam os seus ficheiros em bases de conhecimento estruturadas, indexadas uma única vez e consultáveis indefinidamente. Esta é a base do RAG (Retrieval-Augmented Generation) com o Grok, e a diferença nota-se assim que uma equipa de suporte consulta duzentas fichas de produto em vez de um único PDF.
Encare uma coleção como uma pasta inteligente. Deposita documentos, a xAI indexa-os para pesquisa semântica e o Grok consulta esta base para responder com precisão, extraindo as três passagens úteis entre milhares.
Uma API separada e o motivo
Não gere coleções através da API que tem utilizado desde o início do curso. Estas estão sob a alçada da Management API, alojada em management-api.x.ai, com o URL base:
https://management-api.x.ai/v1
Esta separação não é um capricho arquitetural. Criar, modificar ou eliminar uma coleção são operações administrativas com consequências graves, e a xAI exige uma chave dedicada para as mesmas: uma Management API Key, com a permissão AddFileToCollection. O benefício é imediato para as equipas: o serviço que consulta a base a partir da sua aplicação pública recebe a chave padrão e não pode destruir nada; apenas o seu pipeline de ingestão detém a chave de gestão.
Criar a sua primeira coleção
A criação resume-se a uma única chamada com um nome:
curl -X POST https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "technical-docs"}'
A resposta devolve o identificador que deve guardar:
{
"collection_id": "col_xyz789",
"collection_name": "technical-docs",
"created_at": "2026-04-01T10:00:00Z"
}
Escolha este nome com cuidado: ele aparecerá em todas as suas listas e, daqui a seis meses, será a única pista que lhe permitirá distinguir duas bases vizinhas. technical-docs cumpre essa função; test2 não. Adote uma convenção desde a primeira coleção, pois renomear uma base já referenciada por três aplicações custa mais do que nomeá-la corretamente desde o início.
As cinco operações disponíveis
A Management API expõe um conjunto CRUD completo sobre coleções:
| Operação | Método | Endpoint |
|---|---|---|
| Criar | POST | /v1/collections |
| Listar | GET | /v1/collections |
| Detalhes | GET | /v1/collections/{collection_id} |
| Atualizar | PUT | /v1/collections/{collection_id} |
| Eliminar | DELETE | /v1/collections/{collection_id} |
A listagem das suas coleções ocorre sem parâmetros e fornece uma visão geral útil antes de qualquer operação de manutenção:
curl https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
A eliminação segue a mesma lógica, designando o identificador obtido na criação:
curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Uma coisa deve tranquilizá-lo ao executar este comando: eliminar uma coleção remove a indexação, não os ficheiros. Os seus documentos permanecem acessíveis através da Files API e podem ser reindexados noutro local. Perde a estrutura de pesquisa, não a matéria-prima — o que torna a reconstrução de uma base mal organizada muito menos arriscada do que parece.
Pontos-chave
- As coleções agrupam os seus ficheiros em bases de conhecimento indexadas para RAG
- A gestão é feita através da Management API (
management-api.x.ai), não da API padrão - É necessária uma Management API Key com a permissão
AddFileToCollection - Os limites são 100.000 ficheiros e 100 GB por conta
- As cinco operações CRUD cobrem criação, leitura, atualização e eliminação