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/ru/",
"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/ru/about.htm",
"representativeQueries": ["о компании и условиях работы", "контакты и реквизиты"]
},
{
"identifier": "urn:air:example.com:article:how-to-choose",
"displayName": "Статья «Как выбрать товар»",
"type": "text/html",
"url": "https://example.com/ru/blog/news_ru/how-to-choose.htm",
"representativeQueries": ["как выбрать товар", "советы перед покупкой"]
},
{
"identifier": "urn:air:example.com:category:laptops",
"displayName": "Категория товаров «Ноутбуки»",
"type": "text/html",
"url": "https://example.com/ru/pers_shop/laptops/",
"representativeQueries": ["ноутбуки в каталоге", "цены на ноутбуки"]
},
{
"identifier": "urn:air:example.com:product:437544",
"displayName": "Товар «Ноутбук, модель 437544»",
"type": "text/html",
"url": "https://example.com/ru/pers_shop/laptops/laptop-model_437544.htm",
"representativeQueries": ["характеристики и цена ноутбука", "отзывы о модели"]
},
{
"identifier": "urn:air:example.com:blog:news",
"displayName": "Категория блога «Новости»",
"type": "text/html",
"url": "https://example.com/ru/blog/news_ru/",
"representativeQueries": ["новости магазина", "полезные статьи"]
},
{
"identifier": "urn:air:example.com:producer:brand",
"displayName": "Производитель «Brand»",
"type": "text/html",
"url": "https://example.com/ru/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/ru/pers_shop/ - Доставка: https://example.com/ru/delivery.htm - Оплата: https://example.com/ru/payment.htm ## Компания - О нас: https://example.com/ru/about.htm - Контакты: https://example.com/ru/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.