Metadados e Campos Personalizados
Nesta página
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ção | Efeito |
|---|---|
required: true | Cada documento deve conter este metadado |
unique: true | Dois documentos não podem partilhar o mesmo valor |
inject_into_chunk: true | O 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
fieldsassocia metadados chave-valor a cada documentofield_definitionsao nível da coleção definem regras: required, unique, inject_into_chunk- A opção
inject_into_chunkmelhora 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