Cloudflare AI Search: поиск по сайту и файлам для приложения и агента

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

Руководство рассчитано на разработчика, который умеет выполнять команды Wrangler и работать с HTTP. Понадобятся права на Cloudflare и корпус, который можно индексировать. Namespace — именованная группа экземпляров поиска; экземпляр хранит свой источник и настройки. AI Search вышел в GA 1 октября 2026 года, биллинг заявлен с 1 ноября. Новые экземпляры используют гибридный поиск по умолчанию.

Материал основан на официальной документации 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.

Для PDF с включённым OCR и текстовых/кодовых файлов действует предел 10 MiB; для PDF без OCR и других преобразуемых форматов — 4 MiB. MiB равен 1 048 576 байтам. OCR — распознавание текста в изображении — доступен всем аккаунтам, но выключен по умолчанию. Его включение меняет способ индексации и запускает полное переиндексирование. Файлы сверх предела не индексируются и попадают в журнал ошибок.

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

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

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

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

• Аккаунт Cloudflare и домен, которым вы владеете, если источником будет сайт.
• Поддерживаемый Node.js ≥22, Wrangler (сверена версия 4.147.0) и доступ, позволяющий создавать 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 установлен и авторизован в выбранном аккаунте. Имена pimenov-ai и сайт в командах показывают пример конфигурации: замените их своим namespace, именем экземпляра и сайтом, которым вы владеете. Создание, индексирование, jobs и запросы обращаются к Cloudflare; это облачные действия, которые могут расходовать квоты и средства.

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; формат запроса выбирайте по текущей документации. Для первого запуска достаточно Dashboard: загрузите один документ и дождитесь его успешной индексации во вкладке Items.

Поиск из Cloudflare Worker

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

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

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

Ниже минимальный HTTP-обработчик для публичного несекретного корпуса. Публичный Worker возвращает фрагменты каждому посетителю. Для закрытой базы нужна проверка пользователя и его доступа к корпусу до search(); имя экземпляра не заменяет её. Пример предполагает уже созданный Worker, где main указывает на этот файл, и добавленную namespace-привязку:

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 в объект namespace-binding. Wrangler будет обращаться к развёрнутому AI Search даже при локальном запуске Worker; запросы могут расходовать квоты и оплачиваться по действующим условиям. Локального автономного индекса эта настройка не создаёт.

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

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

Агент вызывает 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 embedding и reranking включены в AI Search; они больше не попадают в отдельный счёт Workers AI или журналы AI Gateway. Генерация ответа, переписывание запроса и внешние провайдеры продолжают использовать ваш аккаунт и gateway и учитываются по соответствующим правилам.

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

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

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

AI Search вышел в общую доступность (GA) 1 октября 2026 года. Опубликованный биллинг начинается 1 ноября 2026 года. Лимиты и будущие ставки ниже заново сверены 3 октября.

С 1 ноября каждый аккаунт получает в месяц 5 млн токенов индексируемого содержимого, 10 ГБ-месяцев хранения, 1 000 семантических и 1 000 полнотекстовых запросов. Это включённые объёмы, а не обещание неограниченного бесплатного поиска.

Токены считаются по конечным индексируемым фрагментам, с повторным учётом перекрывающегося текста. Изображения и OCR используют общую включённую квоту индексации, но сверх неё применяются основная и дополнительная ставки. Генерация ответа, переписывание запроса и внешние модельные провайдеры могут оплачиваться отдельно. Текущие лимиты и тарифы.

Для сайта одновременно действуют несколько ограничений. Например, 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
• Лимиты и стоимость

Источники и изменяемые параметры заново сверены 3 октября 2026 года. Контрольные запросы выше — план оценки качества; измерений на заполненном экземпляре при подготовке не выполняли.

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

Для агента с собственной памятью откройте Agents SDK и Durable Objects.

При выборе поиска сначала определите разрешённый корпус, контрольные вопросы и правила доступа к найденным фрагментам.

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