AI Catalog (ai-catalog.json): що це і як налаштувати
Покроково: навіщо потрібен ai-catalog.json, які поля обов'язкові, як вказати каталог з мовою та pers_shop, де керувати сторінкою ai_catalog на BooStore і як працює перевірка JSON.
Зміст
1. Що таке ai-catalog.json і навіщо він потрібен
ai-catalog.json — машиночитний каталог ключових ресурсів сайту для ШІ-агентів і LLM. Він доповнює llms.txt: llms.txt дає текстовий опис, а AI Catalog перелічує конкретні сторінки з ідентифікаторами та типовими запитами користувачів.
- Допомагає ШІ-пошуку та агентам правильно зрозуміти структуру магазину й знайти потрібні розділи.
- Не замінює sitemap.xml і robots.txt: у них інші завдання.
- Публікується за адресою /.well-known/ai-catalog.json і доступний без авторизації.
2. Специфікація 1.0: обов'язкові правила
Перевірка виконується під час збереження сторінки ai_catalog. Якщо JSON не відповідає правилам, сторінка не зберігається.
- specVersion — строго рядок "1.0" (число без лапок — помилка).
- host — лише displayName.
- entries — мінімум один запис.
- identifier — urn:air:<домен>:<категорія>:<ім'я>, латиниця без пробілів.
- url — повна https:// адреса, що відповідає 200.
- representativeQueries — від 2 до 5 рядків.
3. Мінімальний приклад
Стандартні значення BooStore для звичайного сайту — лише головна сторінка свого домену з мовою. Далі ресурси можна додати вручну.
{
"specVersion": "1.0",
"host": {
"displayName": "Назва сайту"
},
"entries": [
{
"identifier": "urn:air:example.com:site:home",
"displayName": "Головна сторінка",
"type": "text/html",
"url": "https://example.com/ua/",
"representativeQueries": [
"про сайт і його розділи",
"контакти та умови роботи"
]
}
]
}
4. Розширений приклад: різні типи даних
У розширеному прикладі — різні типи даних: сторінка, стаття, категорія товарів, товар, категорія блогу та виробник. Для каталогу вказуйте мову та pers_shop: /<lang>/pers_shop/, /<lang>/pers_shop/<category>/, /<lang>/pers_shop/<category>/<slug>_<id>.htm.
{
"specVersion": "1.0",
"host": { "displayName": "Мій магазин" },
"entries": [
{
"identifier": "urn:air:example.com:page:about",
"displayName": "Сторінка «Про нас»",
"type": "text/html",
"url": "https://example.com/ua/about.htm",
"representativeQueries": ["про компанію та умови роботи", "контакти та реквізити"]
},
{
"identifier": "urn:air:example.com:article:how-to-choose",
"displayName": "Стаття «Як вибрати товар»",
"type": "text/html",
"url": "https://example.com/ua/blog/news_ua/how-to-choose.htm",
"representativeQueries": ["як вибрати товар", "поради перед покупкою"]
},
{
"identifier": "urn:air:example.com:category:laptops",
"displayName": "Категорія товарів «Ноутбуки»",
"type": "text/html",
"url": "https://example.com/ua/pers_shop/laptops/",
"representativeQueries": ["ноутбуки в каталозі", "ціни на ноутбуки"]
},
{
"identifier": "urn:air:example.com:product:437544",
"displayName": "Товар «Ноутбук, модель 437544»",
"type": "text/html",
"url": "https://example.com/ua/pers_shop/laptops/laptop-model_437544.htm",
"representativeQueries": ["характеристики та ціна ноутбука", "відгуки про модель"]
},
{
"identifier": "urn:air:example.com:blog:news",
"displayName": "Категорія блогу «Новини»",
"type": "text/html",
"url": "https://example.com/ua/blog/news_ua/",
"representativeQueries": ["новини магазину", "корисні статті"]
},
{
"identifier": "urn:air:example.com:producer:brand",
"displayName": "Виробник «Brand»",
"type": "text/html",
"url": "https://example.com/ua/producer/brand/",
"representativeQueries": ["товари виробника Brand", "бренд та його моделі"]
}
]
}
5. Функціональна сторінка AI Catalog
AI Catalog — це функціональна сторінка в розділі «Сторінки». Через неї ви заповнюєте публічний /.well-known/ai-catalog.json: вказуєте назву сайту та ключові сторінки, які мають знати ШІ-агенти.
- Для головного сайту BooStore.pro каталог платформи вже заповнено: опис можливостей, llms.txt і документація.
- Для вашого сайту каталог заповнюється вручну на сторінці AI Catalog.
- Стандартне значення для звичайного сайту — лише головна сторінка з мовою; решту ресурсів додайте самостійно.
Публічна адреса файлу — /.well-known/ai-catalog.json.
6. Як заповнити /.well-known/ai-catalog.json
Відкрийте «Сторінки» → «Створити функціональну сторінку» → AI Catalog. Вставте свій JSON у поле тексту й збережіть. Готового прикладу в полі немає — використовуйте приклади вище.
7. Рекомендації
- Вказуйте лише реальні URL, що віддають 200.
- Використовуйте 2–5 природних запитів на запис.
- Не дублюйте записи й не змішуйте мови в URL.
- Оновлюйте каталог при зміні структури магазину.
- Перевіряйте JSON перед збереженням: помилки показуються в адмінці.
8. Повна інструкція: розміщення, robots/sitemap і перевірка
Що це. AI Catalog — машиночитний маніфест сайту для ШІ-агентів. Детально про призначення — у цій статті: AI Catalog.
Де розміщувати. Публічний файл має відповідати за адресою /.well-known/ai-catalog.json у корені домену. На BooStore додатково працюють /ai-catalog.json (301 на well-known) і мовні версії /{lang}/ai-catalog.json для сумісності.
Як створити на BooStore. Відкрийте «Сторінки» → «Створити функціональну сторінку» → AI Catalog, вставте JSON у поле тексту й збережіть. Під час збереження перевіряються specVersion, host.displayName, entries, identifier, https-URL і representativeQueries. Жорсткого ліміту кількості записів немає — рекомендується до 500. Якщо JSON більший за 512 КБ, показується попередження, але збереження дозволено.
Sitemap і robots. Не додавайте ai-catalog.json і llms.txt до sitemap.xml: карта сайту для HTML-сторінок. У robots.txt їх не потрібно закривати; корисно явно дозволити: Allow: /.well-known/ai-catalog.json і Allow: /llms.txt.
Рекомендуємо разом з llms.txt. Додайте /llms.txt: він дає ШІ текстовий опис, а AI Catalog — структурований список ключових ресурсів. Детальніше: посібник з llms.txt.
Приклад llms.txt
Файл створюється так само, як AI Catalog: «Сторінки» → «Створити функціональну сторінку» → тип «LLM / llms.txt». У поле тексту вставте короткий опис сайту та посилання на ключові розділи.
# Назва сайту > Короткий опис сайту й магазину. ## Магазин - Каталог: https://example.com/ua/pers_shop/ - Доставка: https://example.com/ua/delivery.htm - Оплата: https://example.com/ua/payment.htm ## Компанія - Про нас: https://example.com/ua/about.htm - Контакти: https://example.com/ua/contacts.htm
Публічна адреса файлу — /llms.txt у корені домену.
/.well-known/ai-catalog.json і переконайтеся, що відповідь 200, тип application/json, JSON валідний, а URL з entries відкриваються. Помилки валідації показуються в адмінці під час збереження сторінки.- Вказуйте лише реальні
https://-URL, що віддають 200. - Залишайте 2–5 природних запитів у
representativeQueries. - Використовуйте латиницю в
identifierформатуurn:air:домен:категорія:ім'я. - Оновлюйте каталог при зміні структури магазину.
- Не дублюйте записи й не змішуйте мови в URL без потреби.
9. Часті питання
Чим ai-catalog.json відрізняється від llms.txt?
llms.txt — текстова база знань, ai-catalog.json — структурований список ключових ресурсів.
Чи обов'язковий каталог у стандартних значеннях?
Ні. За замовчуванням віддається лише головна сторінка; решту додавайте самостійно.
Що буде, якщо JSON невалідний?
Сторінка не збережеться, в адмінці з'явиться повідомлення про помилку.
Чи потрібен окремий файл у корені?
Ні. Усе заповнюється на функціональній сторінці AI Catalog.
Де має лежати ai-catalog.json?
Правильний шлях — /.well-known/ai-catalog.json у корені домену. Кореневий /ai-catalog.json на BooStore перенаправляється на нього, а мовні версії доступні як /{lang}/ai-catalog.json.
Чи потрібно додавати ai-catalog.json і llms.txt до sitemap.xml?
Ні. Sitemap — для HTML-сторінок. Маніфести й текстові описи туди не додаємо.
Як пов'язані ai-catalog.json і robots.txt?
Закривати файл у robots.txt не потрібно. Навпаки, корисно явно дозволити /.well-known/ai-catalog.json і /llms.txt, щоб пошукові та ШІ-краулери могли їх читати.
Чи можна створити AI Catalog на BooStore без коду?
Так: «Сторінки» → «Створити функціональну сторінку» → AI Catalog. JSON перевіряється на валідність під час збереження, помилки показуються в адмінці. Жорсткого ліміту кількості записів немає, рекомендація — до 500.
Чи потрібно вказувати llms.txt в ai-catalog.json?
Не обов'язково. AI Catalog перелічує ключові HTML-сторінки сайту, а llms.txt — окремий текстовий файл за адресою /llms.txt, який ШІ-агенти знаходять за стандартним шляхом. За бажанням його можна додати в entries як додатковий ресурс, але це не вимога.
Навіщо llms.txt разом з AI Catalog?
llms.txt дає ШІ текстовий опис сайту, а AI Catalog — структурований список ресурсів. Їх краще використовувати разом. Інструкція: посібник з llms.txt.