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

Criar e gerir coleções

Aula 5 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. De ficheiros isolados a uma base de conhecimento
  2. Uma API separada e o motivo
  3. Criar a sua primeira coleção
  4. As cinco operações disponíveis
  5. Pontos-chave

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.

100k
Ficheiros por conta
100 GB
Capacidade total
CRUD
Operações completas
$2.50
Por 1.000 pesquisas

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çãoMétodoEndpoint
CriarPOST/v1/collections
ListarGET/v1/collections
DetalhesGET/v1/collections/{collection_id}
AtualizarPUT/v1/collections/{collection_id}
EliminarDELETE/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