← Обзор / ai-search / configuration / retrieval / public-endpoint

Публичные конечные точки пространства имён

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

Эндпойнт пространства имён обслуживает те же пути и принимает те же настройки, что и эндпойнт экземпляра, включая пользовательские домены и Cloudflare Access. См. Настройки публичной конечной точки. На этой странице описаны особенности пространств имён.

Задайте public_endpoint_params на пространстве имён и укажите экземпляры, которые нужно открыть в instances_allowed.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": {
      "enabled": true,
      "instances_allowed": ["docs", "blog", "support"]
    }
  }'

Ответ возвращает сгенерированный public_endpoint_id. Имя хоста пространства имён имеет префикс ns-:

https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search

Включение конечной точки пространства имён не изменяет конечные точки экземпляров внутри него. Каждая из них включается и отключается отдельно.

instances_allowed определяет, к каким экземплярам может обращаться эндпойнт.

• Каждая запись должна быть существующим экземпляром в этом пространстве имён. Для неизвестной записи возвращается ошибка 7097.
• Список содержит до 10 экземпляров.
• Пустой список означает, что искать нечего. Именно в таком состоянии находится пространство имён, когда вы впервые включаете эндпойнт.
• Удаление экземпляра или его перенос в другое пространство имён удаляет его из allowlist.

Запрос, который не разрешается ни в один доступный для поиска экземпляр, возвращает 404 с ошибкой 60013. Этот ответ одинаков независимо от того, не существует ли экземпляр, находится ли он вне allowlist или allowlist пуст, поэтому вызывающая сторона не может определить, какие экземпляры входят в пространство имён.

По умолчанию запрос выполняет поиск по всем экземплярам в allowlist. Чтобы ограничить отдельный запрос, задайте ai_search_options.instance_ids в теле запроса.

curl https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {
        "content": "How do I configure AI Search?",
        "role": "user"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["docs", "support"]
    }
  }'

Каждое значение должно быть в allowlist. Правила для этого поля:

• Если не указать это поле или задать ему значение null, выполняется поиск по всему allowlist.
• Некорректное значение, например пустой массив или нестроковый элемент, возвращает 400 с ошибкой 60012.
• Значение вне allowlist возвращает 404 с ошибкой 60013.

Задайте public_endpoint_params к null. Это очищает конфигурацию и прекращает обслуживание трафика, но сохраняет идентификатор, чтобы URL-адрес использовался повторно, если вы снова включите конечную точку.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_endpoint_params": null
  }'