Cloudflare AI Search — как превратить сайт или набор файлов в поисковый индекс для агента

Cloudflare AI Search превращает сайт, R2-бакет или файлы во встроенном хранилище в поисковый индекс, к которому можно обращаться из Worker или приложения. Для запросов доступны векторный, ключевой и гибридный режимы.

Материал основан на официальной документации Cloudflare. Команды и настройки ниже не проверялись на рабочем аккаунте автора, поэтому после запуска ориентируйтесь на состояния Items и Jobs, вывод Wrangler и фактический ответ API.

Оглавление

1. Что входит в AI Search
2. Какие данные можно индексировать
3. Что подготовить до запуска
4. Быстрый запуск поиска по сайту
5. Загрузка документов и файлов
6. Поиск из Cloudflare Worker
7. Подключение к ИИ-агенту
8. Обновление индекса
9. Модели и отдельная тарификация
10. Когда AI Search подходит
11. Лимиты и стоимость
12. Что делать, если поиск не работает
13. План мини-теста на материалах pimenov.ai

Что входит в AI Search

AI Search позволяет подключить сайт, принадлежащий вам, R2 Bucket или встроенное хранилище. Файлы можно загружать непосредственно в экземпляр через Dashboard, а к приложению подключать AI Search через Workers Binding или REST API.

При поиске API возвращает фрагменты (chunks) с оценкой совпадения и сведениями об исходном документе. На уровне запроса доступны режимы vector, keyword и hybrid, ограничение числа результатов, порог совпадения, фильтры по метаданным (metadata), переписывание запроса, расширение контекста, повышение приоритета по метаданным и reranking.

Полезные сценарии

Namespace binding позволяет искать сразу по нескольким экземплярам. В запросе можно явно выбрать от одного до десяти instance_ids, а в ответе проверить instance_id у каждого фрагмента.

Какие данные можно индексировать

AI Search поддерживает три источника:

• Built-in storage — встроенное хранилище, доступное в каждом экземпляре;
• Website — домен, которым вы владеете;
• R2 Bucket — документы в Cloudflare R2.

Поддерживаются Markdown, TXT, JSON, YAML, HTML, XML, PDF, DOCX, таблицы, изображения и распространённые форматы исходного кода. Полный список расширений приведён в официальном описании источников данных. Богатые форматы преобразуются в Markdown.

Максимальный размер одного файла на 8 сентября 2026 года составляет 4 МБ. Файлы, превышающие этот лимит, не индексируются и появляются в журнале ошибок.

Для сайта Wrangler поддерживает два режима поиска страниц:

• sitemap читает XML sitemap и используется по умолчанию;
• discover рекурсивно переходит по ссылкам.

Для большого сайта заранее ограничьте индексируемые пути флагами --include-items и --exclude-items, чтобы в индекс не попадали лишние разделы и дубли.

Что подготовить до запуска

• Аккаунт Cloudflare и домен, которым вы владеете, если источником будет сайт.
• Установленный Wrangler и доступ, позволяющий создавать namespace и экземпляры AI Search.
• Решение использовать sitemap или discover.
• Проект Cloudflare Worker, если нужен собственный HTTP endpoint.

Включаемые и исключаемые URL можно задать флагами --include-items и --exclude-items, например оставить только /articles/, /blog/ и /knowledge/.

Быстрый запуск поиска по сайту

Через Dashboard откройте AI Search, выберите Create Instance, задайте имя, при необходимости подключите сайт или R2 Bucket и создайте экземпляр. После создания файлы загружаются через вкладку Items.

Для CLI ниже предполагается, что Wrangler уже установлен и авторизован:

npx wrangler ai-search namespace create pimenov-ai

Если namespace уже существует, пропустите эту команду.

Выберите один из вариантов создания экземпляра. При наличии XML sitemap:

npx wrangler ai-search create pimenov-ai-search --namespace pimenov-ai --source https://pimenov.ai --type web-crawler --parse-type sitemap --hybrid-search --custom-metadata category:text

Если sitemap не подходит, используйте вместо предыдущей команды режим discover:

npx wrangler ai-search create pimenov-ai-search --namespace pimenov-ai --source https://pimenov.ai --type web-crawler --parse-type discover --hybrid-search --custom-metadata category:text

Флаг --parse-type присутствует в справочнике Wrangler и принимает значения sitemap и discover. Перед копированием команд в автоматизацию полезно сверить установленную версию:

npx wrangler ai-search create --help

Проверьте статистику экземпляра:

npx wrangler ai-search stats pimenov-ai-search --namespace pimenov-ai

Для задания индексации используйте команды jobs list, jobs get и jobs logs с тем же namespace.

После завершения индексации выполните первый запрос:

npx wrangler ai-search search pimenov-ai-search --namespace pimenov-ai --query 'Как подключить ИИ-агента к данным сайта?'

Проверяемый результат: ответ содержит найденные фрагменты, оценки релевантности и сведения об исходных материалах.

Загрузка документов и файлов

Встроенное хранилище доступно в каждом экземпляре. Для загрузки через Dashboard откройте AI Search, выберите экземпляр, перейдите во вкладку Items и добавьте документы. AI Search индексирует загруженные файлы автоматически.

Если metadata участвует в фильтрации, заранее объявите пользовательские поля в схеме экземпляра, например через --custom-metadata category:text. Доступные типы полей Wrangler перечисляет в справке CLI.

Один экземпляр может использовать внешний источник, подключённый при создании, и принимать дополнительные файлы через встроенное хранилище. Параметры программной загрузки через Items API в проверенных snapshots не приведены, поэтому здесь не приводится неподтверждённый пример кода.

Поиск из Cloudflare Worker

Для экземпляра в namespace pimenov-ai используйте namespace binding. Прямая привязка ai_search предназначена для экземпляра в namespace default.

Добавьте binding в wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "pimenov-ai"
    }
  ]
}

Минимальный Worker для гибридного поиска:

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const query = url.searchParams.get('q');

    if (!query) {
      return Response.json(
        { error: 'Передайте параметр q' },
        { status: 400 }
      );
    }

    const instance = env.AI_SEARCH.get('pimenov-ai-search');
    const result = await instance.search({
      query,
      ai_search_options: {
        retrieval: {
          retrieval_type: 'hybrid',
          max_num_results: 5
        },
        reranking: {
          enabled: true
        }
      }
    });

    return Response.json(result);
  }
};

Разверните Worker:

npx wrangler deploy

Wrangler выведет его адрес. Подставьте URL в проверочный запрос:

curl 'https://<worker-name>.<subdomain>.workers.dev/?q=как+подключить+агента'

Успешный ответ содержит массив chunks. У каждого фрагмента доступны текст, итоговая оценка, сведения об исходном документе и детали ранжирования.

Для локальной разработки добавьте "remote": true в конфигурацию binding. Wrangler будет проксировать запросы к развёрнутому экземпляру.

Подключение к ИИ-агенту

Поиск как инструмент агента

Агент вызывает search(), получает фрагменты и формирует ответ в собственном цикле. Такой вариант позволяет отдельно управлять промптом, цитатами и проверкой источников.

Готовый ответ через Chat Completions

Метод chatCompletions() извлекает контекст и передаёт его модели. Непотоковый ответ содержит готовый текст и массив использованных chunks. При stream: true сначала приходит событие с найденными фрагментами, затем SSE-поток ответа.

Поиск по нескольким экземплярам

Namespace binding позволяет искать сразу по нескольким экземплярам:

const result = await env.AI_SEARCH.search({
  messages: [
    { role: 'user', content: 'Как настроить поиск по документации?' }
  ],
  ai_search_options: {
    instance_ids: ['product-docs', 'customer-project']
  }
});

В одном запросе можно указать от одного до десяти экземпляров. Каждый фрагмент содержит instance_id, а ошибки отдельных экземпляров возвращаются в массиве errors.

Обновление индекса

Файлы из встроенного хранилища индексируются после загрузки. Для внешних источников состояние заданий индексации проверяйте через Jobs.

Ручное задание индексации для namespace pimenov-ai запускается так:

npx wrangler ai-search jobs create pimenov-ai-search --namespace pimenov-ai

Актуальный Wrangler поддерживает --namespace для команд jobs list, jobs create, jobs get, jobs cancel и jobs logs. Это позволяет запускать обновление из CI/CD и затем проверять конкретное задание.

Модели и отдельная тарификация

При создании и обновлении экземпляра Wrangler принимает параметры --embedding-model и --generation-model:

npx wrangler ai-search update pimenov-ai-search --namespace pimenov-ai --embedding-model 'EMBEDDING_MODEL_ID' --generation-model 'GENERATION_MODEL_ID'

Замените placeholders на идентификаторы моделей из актуальной конфигурации. Перед изменением embedding-модели сравните качество поиска на контрольном наборе запросов.

Использование Workers AI и AI Gateway учитывается отдельно от AI Search по правилам этих сервисов.

Когда AI Search подходит

AI Search подходит, когда нужен готовый поиск по сайту, R2 или обычным документам с подключением к Worker или приложению. Если вы сравниваете его с собственным контуром на Vectorize, API и стоимость Vectorize нужно проверять отдельно: в использованных snapshots этих сведений нет.

Лимиты и стоимость

На 8 сентября 2026 года AI Search находится в открытой бете и бесплатен в пределах установленных лимитов. Workers AI и AI Gateway тарифицируются отдельно. Cloudflare сообщит подробности будущего биллинга минимум за 30 дней до его начала.

Для сайта одновременно действуют несколько ограничений. Например, discover crawl принимает до 100 000 страниц, но ограничения на файлы в экземпляре и страницы в день также применяются. Итоговое число страниц определяется наиболее низким из действующих лимитов. На Workers Free ограничение составляет 500 страниц в день.

Хранилище, векторная индексация и Browser Run, который используется при обходе сайта, включены в AI Search и отдельно не тарифицируются. У старых экземпляров могут сохраняться R2-бакеты прежней архитектуры. AI Search больше не записывает в них данные, но оставшиеся объекты могут продолжать учитываться в расходах R2.

Что делать, если поиск не работает

План мини-теста на материалах pimenov.ai

Фактические оценки нужно снять после создания и заполнения экземпляра. Без доступа к нему нельзя публиковать достоверные показатели качества.

Запустите каждый запрос в vector- и hybrid-режиме. Зафиксируйте:

1. место ожидаемой страницы;
2. число релевантных результатов в топ-5;
3. правильность URL источника;
4. наличие лишних страниц во фрагментах;
5. соответствие сгенерированного ответа найденному контексту.

Для небольшого пилота можно принять такой редакционный порог:

• точные названия продуктов попадают на первое место;
• минимум пять ожидаемых страниц из шести входят в топ-3;
• в топ-5 находится не более одного явно постороннего результата;
• сгенерированный ответ не содержит утверждений, которых нет в найденных фрагментах.

Если vector хорошо отвечает на общие вопросы, но теряет названия, команды или коды ошибок, сравните его с hybrid. Если правильные документы находятся, но расположены низко, проверьте reranking. Лишние страницы устраняйте настройкой путей и повторной индексацией.

Официальные ссылки

• Начало работы через Dashboard
• Источники и поддерживаемые файлы
• Wrangler CLI
• Workers binding
• Лимиты и стоимость

Источники и изменяемые параметры проверены 8 сентября 2026 года.

Следующий шаг

Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Связанные материалы

• Блог: Gemini Embedding 2 вышел — и мультимодальный поиск стал на шаг ближе к продакшену
• База знаний: BAAI/bge-m3 — мультиязычная embedding-модель для self-hosted RAG
• База знаний: Agent-ready сайт — методология подготовки для ИИ-агентов

Если вы выбираете конфигурацию AI Search для сайта, документации или проектных файлов, обсуждение полезно, когда нужно сопоставить требования к источникам, выдаче и эксплуатации.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov