Премини към основното съдържание
Български— Изберете език
Меню

Метаданни и потребителски полета

Урок 7 от 16 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Контекст, който документът не носи
  2. Прикачване на полета към документ
  3. Задаване на правила на ниво колекция
  4. Опцията, която променя релевантността
  5. Три доказани схеми
  6. Поддържане на последователна схема
  7. Ключови изводи

Контекст, който документът не носи

Техническият доклад не винаги включва името на автора, годината на написване или нивото на поверителност в основния текст. Въпреки това тези детайли правят разликата между търсене, което открива правилния документ, и такова, което връща три нерелевантни резултата. Системата за метаданни на колекциите служи точно за тази цел: да свързва структурирана информация с всеки документ, която търсачката може да използва и Вие можете да филтрирате.

Прикачване на полета към документ

Когато добавяте документ, параметърът 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 подобрява релевантността на търсенето, като добавя метаданни към индексираното съдържание
  • Стандартизирайте вашите схеми за метаданни, за да поддържате последователност на колекциите