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

Metadados e Campos Personalizados

Aula 7 de 16 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Contexto que o documento não transporta
  2. Anexar campos a um documento
  3. Definir regras ao nível da coleção
  4. A opção que altera a relevância
  5. Três esquemas comprovados
  6. Manter um esquema consistente
  7. Pontos-chave

Contexto que o documento não transporta

Um relatório técnico nem sempre inclui no corpo do texto o nome do autor, o ano de redação ou o nível de confidencialidade. No entanto, são estes detalhes que fazem a diferença entre uma pesquisa que encontra o documento certo e outra que devolve três resultados irrelevantes. O sistema de metadados de coleções serve exatamente para isso: associar informações estruturadas a cada documento, permitindo que a pesquisa as explore e que o utilizador as utilize para filtrar.

Anexar campos a um documento

Ao adicionar um documento, o parâmetro fields aceita pares chave-valor que define livremente:

await client.collections.upload_document(
    collection_id=collection_id,
    name="technical-report-q1",
    data=pdf_content,
    fields={
        "author": "Marie Dupont",
        "year": "2026",
        "department": "R&D",
        "document_type": "report",
        "confidentiality": "internal"
    }
)

Nenhum esquema é imposto a este nível: os nomes dos campos são da sua escolha. Esta liberdade parece confortável para o primeiro documento, mas torna-se um problema no centésimo, quando author, auteur e Author coexistem na mesma coleção sem que nenhum filtro funcione.

Definir regras ao nível da coleção

É aqui que entram as field_definitions, declaradas na coleção. Transformam uma convenção oral numa restrição verificada pela API. Existem três configurações:

ConfiguraçãoEfeito
required: trueCada documento deve conter este metadado
unique: trueDois documentos não podem partilhar o mesmo valor
inject_into_chunk: trueO metadado é adicionado ao conteúdo indexado

Uma definição combina estas configurações campo por campo:

{
  "field_definitions": [
    {
      "name": "author",
      "required": true,
      "inject_into_chunk": true
    },
    {
      "name": "document_id",
      "required": true,
      "unique": true
    },
    {
      "name": "year",
      "required": false,
      "inject_into_chunk": true
    }
  ]
}

Leia este exemplo como uma política de documentos: cada documento tem um autor e um ID; esse ID pertence apenas a um documento — o que bloqueia duplicados na ingestão — e o ano permanece opcional para evitar a rejeição de itens sem data.

A opção que altera a relevância

Destas três configurações, inject_into_chunk é a única que afeta a qualidade das respostas e merece uma análise mais atenta. Durante a indexação, um documento é dividido em fragmentos — chunks — e ativar esta opção copia o valor do campo para cada um deles.

Concretamente, com author: "Marie Dupont" e inject_into_chunk: true, cada chunk indexado transporta este nome. Uma pergunta como «O que escreveu Marie Dupont sobre a latência da rede?» tem então hipóteses de acertar no alvo, uma vez que o nome aparece no conteúdo pesquisado. Sem injeção, a mesma pergunta depende apenas do texto do relatório, onde o autor pode aparecer apenas na capa.

Ative, portanto, a injeção para campos que transportam contexto — autor, departamento, ano, categoria — e mantenha-a desativada para campos administrativos como um ID interno, data de carregamento ou estado de validação, que apenas adicionariam ruído.

Três esquemas comprovados

Os metadados úteis não são inventados no abstrato: resultam das perguntas colocadas à base de dados. Uma base de documentação técnica organiza-se em torno do produto e da versão, pois a primeira pergunta de um utilizador é quase sempre «qual a versão?»:

{
  "fields": {
    "product": "Grok API",
    "version": "v1",
    "type": "reference",
    "language": "en"
  }
}

Uma base de conhecimento de RH, por outro lado, raciocina por categoria e data de entrada em vigor, já que a resposta errada nesse contexto é frequentemente uma política revogada:

{
  "fields": {
    "category": "hr-policy",
    "effective_date": "2026-01-01",
    "department": "all",
    "status": "active"
  }
}

Finalmente, uma base jurídica estrutura-se em torno das partes, tipo de contrato e expiração, permitindo recuperar acordos próximos do fim da validade numa única consulta:

{
  "fields": {
    "contract_type": "vendor",
    "party": "Acme Corp",
    "expiration": "2027-06-30",
    "jurisdiction": "France"
  }
}

Manter um esquema consistente

A consistência perde-se sempre pelos mesmos canais, e bastam alguns hábitos para a manter. Padronize os formatos dos nomes dos campos — snake_case, em inglês, sem misturar línguas. Limite o seu número: cinco a dez campos cobrem a maioria das necessidades; além disso, os custos de manutenção superam os ganhos de relevância. Utilize inject_into_chunk com discernimento, pois cada campo injetado aumenta o tamanho dos chunks e, consequentemente, os custos de armazenamento. Por fim, documente o esquema esperado para cada coleção num ficheiro acessível à equipa: quando várias pessoas o alimentam, é esse ficheiro, e não a memória do criador, que garante a consistência.

Pontos-chave

  • fields associa metadados chave-valor a cada documento
  • field_definitions ao nível da coleção definem regras: required, unique, inject_into_chunk
  • A opção inject_into_chunk melhora a relevância da pesquisa ao adicionar metadados ao conteúdo indexado
  • Padronize os seus esquemas de metadados para manter a consistência da coleção