Метаданни и потребителски полета
На тази страница
Контекст, който документът не носи
Техническият доклад не винаги включва името на автора, годината на написване или нивото на поверителност в основния текст. Въпреки това тези детайли правят разликата между търсене, което открива правилния документ, и такова, което връща три нерелевантни резултата. Системата за метаданни на колекциите служи точно за тази цел: да свързва структурирана информация с всеки документ, която търсачката може да използва и Вие можете да филтрирате.
Прикачване на полета към документ
Когато добавяте документ, параметърът fields приема двойки ключ-стойност, които дефинирате свободно:
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"
}
)
На това ниво не се налага никаква схема: имената на полетата са Ваш избор. Тази свобода изглежда удобна за първия документ, но се превръща в проблем при стотния, когато author, auteur и Author съществуват едновременно в една и съща колекция, без нито един филтър да работи коректно.
Задаване на правила на ниво колекция
Тук идват на помощ field_definitions, декларирани върху колекцията. Те превръщат едно устно споразумение в ограничение, проверено от API. Съществуват три настройки:
| Настройка | Ефект |
|---|---|
required: true | Всеки документ трябва да съдържа тези метаданни |
unique: true | Два документа не могат да споделят една и съща стойност |
inject_into_chunk: true | Метаданните се добавят към индексираното съдържание |
Една дефиниция комбинира тези настройки поле по поле:
{
"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
}
]
}
Разгледайте този пример като политика за документи: всеки документ има автор и ID, като този ID принадлежи само на един документ – което блокира дубликатите при зареждане – а годината остава незадължителна, за да не се отхвърлят недатирани елементи.
Опцията, която променя релевантността
От тези три настройки, inject_into_chunk е единствената, която влияе върху качеството на отговорите, и тя заслужава по-внимателен поглед. По време на индексирането документът се разделя на фрагменти (chunks) и активирането на тази опция копира стойността на полето във всеки от тях.
Конкретно, при author: "Marie Dupont" и inject_into_chunk: true, всеки индексиран фрагмент носи това име. Въпрос като „Какво е написала Marie Dupont за латентността на мрежата?“ тогава има шанс да улучи целта, тъй като името се появява в търсеното съдържание. Без инжектиране, същият въпрос разчита единствено на текста на доклада, където авторът може да се появи само на корицата.
Затова активирайте инжектирането за полета, носещи контекст – автор, отдел, година, категория – и го оставете изключено за административни полета като вътрешен ID, дата на качване или статус на валидиране, които биха добавили само шум.
Три доказани схеми
Полезните метаданни не се измислят в абстрактен план: те произтичат от въпросите, задавани на базата данни. Базата с техническа документация се организира около продукт и версия, тъй като първият въпрос на потребителя почти винаги е „коя версия?“:
{
"fields": {
"product": "Grok API",
"version": "v1",
"type": "reference",
"language": "en"
}
}
Базата знания за човешки ресурси обаче разсъждава чрез категория и дата на влизане в сила, тъй като грешният отговор там най-често е отменена политика:
{
"fields": {
"category": "hr-policy",
"effective_date": "2026-01-01",
"department": "all",
"status": "active"
}
}
Накрая, правната база се структурира около страните, типа договор и изтичане на срока, което Ви позволява да извлечете споразумения, близки до изтичане на валидността им, с една заявка:
{
"fields": {
"contract_type": "vendor",
"party": "Acme Corp",
"expiration": "2027-06-30",
"jurisdiction": "France"
}
}
Поддържане на последователна схема
Последователността винаги се губи по едни и същи канали и няколко навика са достатъчни, за да я запазите. Стандартизирайте форматите на имената на полетата – snake_case, на английски език, без смесване на езици. Ограничете броя им: пет до десет полета покриват повечето нужди; отвъд това разходите за поддръжка надвишават ползите за релевантност. Боравете с inject_into_chunk с разбиране, тъй като всяко инжектирано поле увеличава размера на фрагментите, а оттам и разходите за съхранение. Накрая, документирайте очакваната схема за всяка колекция във файл, достъпен за екипа: щом множество хора я подхранват, този файл, а не паметта на създателя, гарантира последователност.
Ключови изводи
fieldsсвързва метаданни тип ключ-стойност с всеки документfield_definitionsна ниво колекция дефинират правила: required, unique, inject_into_chunk- Опцията
inject_into_chunkподобрява релевантността на търсенето, като добавя метаданни към индексираното съдържание - Стандартизирайте вашите схеми за метаданни, за да поддържате последователност на колекциите