← Обзор / ai-search / api / migration

Миграция REST API

Эндпойнты AutoRAG API это устаревший REST API для AI Search. Он продолжит работать, но все новые функции и улучшения доступны только через новый Конечные точки API AI Search.

Устаревшие эндпойнты AutoRAG API по адресу /autorag/rags/ заменены новыми конечными точками в /ai-search/instances/.

Новый API также включает эндпойнты для управление экземплярами, элементы, а также поиск на уровне пространства имён которые недоступны в устаревшем API. Информацию об устаревших эндпойнтах см. в Справочник по AutoRAG API.

Устаревшие эндпойнты AutoRAG использовали AutoRAG разрешение API-токена. Новые эндпойнты AI Search требуют AI Search разрешение, поэтому обновите разрешения токена, который вы используете для вызова API. Рекомендуем использовать API-токены аккаунта, которые принадлежат аккаунту, а не отдельному пользователю, а также добавление AI Search разрешение, которое можно найти в ИИ и машинное обучение > AI Search.

1. В панели управления Cloudflare перейдите в Manage Account > API-токены.
2. Выберите Create Token, затем запустите создание пользовательского токена.
3. Введите имя токена.
4. Добавьте политику разрешений и выберите ИИ и машинное обучение > AI Search, затем выберите нужный уровень доступа. AI Search предлагает Чтение, Запуск, а также Изменить доступ.
5. (Необязательно) Задайте фильтрацию по IP-адресу клиента и срок действия токена.
6. Создайте токен и скопируйте его значение.

1. В панели управления Cloudflare перейдите в Manage Account > API-токены.
2. Выберите токен, который нужно обновить.
3. Добавьте или обновите политику разрешений, включив в неё ИИ и машинное обучение > AI Search с нужным вам уровнем доступа, а затем сохраните.

Полное описание процесса создания токена см. в Создание API-токена.

Как перейти с AutoRAG /ai-search эндпойнт на новый /chat/completions конечная точка:

До (AutoRAG API):

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/autorag/rags/<INSTANCE_NAME>/ai-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "query": "What is Cloudflare?"
  }'

После (AI Search API):

Новый API использует messages в формате массива.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

Как перейти с AutoRAG /search эндпойнт на новый /search конечная точка:

До (AutoRAG API):

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/autorag/rags/<INSTANCE_NAME>/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "query": "What is Cloudflare?"
  }'

После (AI Search API):

Новый API использует messages в формате массива. query также поддерживается строковый формат.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

В старом API AutoRAG, когда stream было установлено в значение true, вы получили бы только потоковый ответ без найденных чанков.

В новом API AI Search потоковые ответы включают чанки. Найденные чанки отправляются первыми в виде chunks событие, за которым следуют потоковые данные ответа. Это позволяет сразу показывать пользователю исходные чанки, одновременно транслируя сгенерированный ответ.

Новый REST API AI Search использует фильтрацию метаданных в стиле Vectorize, которая отличается от формата AutoRAG API. Теперь фильтры вложены в ai_search_options.retrieval.filters в теле запроса. Полную документацию по старому формату см. в Формат фильтра метаданных (устаревший).

Операторы фильтров были переименованы, чтобы использовать $ префикс:

Фильтрация по одному полю метаданных с неявным равенством:

До (AutoRAG API):

{
	"filters": {
		"type": "eq",
		"key": "folder",
		"value": "customer-a/"
	}
}

После (AI Search API):

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": "customer-a/" }
		}
	}
}

Объедините несколько условий, все из которых должны выполняться:

До (AutoRAG API):

{
	"filters": {
		"type": "and",
		"filters": [
			{ "type": "eq", "key": "folder", "value": "customer-a/" },
			{ "type": "gte", "key": "timestamp", "value": "1735689600000" }
		]
	}
}

После (AI Search API):

{
	"ai_search_options": {
		"retrieval": {
			"filters": {
				"folder": "customer-a/",
				"timestamp": { "$gte": 1735689600 }
			}
		}
	}
}

• Документация REST API
• Справочник по API Chat Completions
• Справочник по API поиска
• Устаревший справочник по AutoRAG API