AACsearch
Руководства по миграции

Миграция из Typesense

Пошаговое руководство по переходу с Typesense на AACsearch Engine — миграция индексов, API-ключей и виджетов поиска.

Миграция из Typesense

Это руководство поможет вам перейти с Typesense на AACsearch Engine. Процесс разработан для минимального времени простоя и занимает всего несколько часов.

Обзор миграции

ШагЧто вы делаетеВремя
1Экспортируете индекс из Typesense~5 минут
2Создаёте индекс в AACsearch~5 минут
3Импортируете данные~10 минут
4Настраиваете фильтры и синонимы~15 минут
5Обновляете API-ключи~10 минут
6Обновляете фронтенд~30 минут
7Переключаете на новый эндпоинт~5 минут

Шаг 1: Экспортируйте индекс из Typesense

Используйте CLI Typesense или API:

# Экспортируйте документы в JSON
curl "http://localhost:8108/collections/products/documents/export" \
  -H "X-TYPESENSE-API-KEY: your_api_key" \
  > typesense-export.json

Или используйте Typesense Python-клиент:

import typesense
import json

client = typesense.Client({
  'nodes': [{'host': 'localhost', 'port': '8108', 'protocol': 'http'}],
  'api_key': 'your_api_key',
  'connection_timeout_seconds': 2
})

collection = client.collections['products'].retrieve()
documents = client.collections['products'].documents.export()

with open('typesense-export.json', 'w') as f:
    f.write(documents)

Шаг 2: Создайте индекс в AACsearch

В панели AACsearch или через API:

curl -X POST "https://app.aacsearch.com/api/v1/indexes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "fields": [
      {"name": "id", "type": "string", "indexing": true},
      {"name": "title", "type": "string", "indexing": true},
      {"name": "description", "type": "string", "indexing": true},
      {"name": "price", "type": "float", "sort": true},
      {"name": "category", "type": "string", "facet": true},
      {"name": "rating", "type": "float", "sort": true},
      {"name": "in_stock", "type": "bool", "facet": true}
    ]
  }'

Шаг 3: Импортируйте данные

Преобразуйте экспортированные данные и загрузите их:

# Экспортированные документы обычно идут в формате JSON Lines
# Просто импортируйте их напрямую:
curl -X POST "https://app.aacsearch.com/api/v1/indexes/products/documents/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @typesense-export.json

Или преобразуйте в нужный формат:

import json

# Прочитайте экспортированные документы
with open('typesense-export.json', 'r') as f:
    lines = f.readlines()
    documents = [json.loads(line) for line in lines]

# Убедитесь, что каждый документ имеет поле "id"
for doc in documents:
    if 'id' not in doc:
        doc['id'] = str(doc.get('object_id', ''))  # или другой уникальный идентификатор

# Сохраните в JSON
with open('import-data.json', 'w') as f:
    json.dump(documents, f)

# Загрузите
import requests
with open('import-data.json', 'r') as f:
    response = requests.post(
        'https://app.aacsearch.com/api/v1/indexes/products/documents/batch',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        json=json.load(f)
    )
    print(response.json())

Шаг 4: Настройте параметры поиска

Фильтры (facets)

Преобразуйте параметры из Typesense:

TypesenseAACsearchЗаметки
facet_by: ["category"]"facet": true на полеФильтруемое поле
group_by: ["brand"]Массив строк "type": "string[]"Группировка результатов

Синонимы

Экспортируйте синонимы из Typesense и импортируйте в AACsearch:

# Экспортируйте синонимы из Typesense
curl "http://localhost:8108/synonyms" \
  -H "X-TYPESENSE-API-KEY: your_api_key" \
  > typesense-synonyms.json

# Импортируйте в AACsearch
curl -X POST "https://app.aacsearch.com/api/v1/indexes/products/synonyms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"synonyms": ["спортивная обувь", "кроссовки", "кеды"]},
    {"synonyms": ["телефон", "смартфон", "мобильник"]},
    {"synonyms": ["ноутбук", "лэптоп", "компьютер"]}
  ]'

Сортировка по релевантности

Typesense использует формулу textMatchScore * popularity. AACsearch имеет встроенные стратегии ранжирования:

# Обновите правила ранжирования
curl -X PUT "https://app.aacsearch.com/api/v1/indexes/products/ranking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sortByFields": [
      {"field": "relevance", "order": "desc"},
      {"field": "rating", "order": "desc"},
      {"field": "price", "order": "asc"}
    ]
  }'

Шаг 5: Обновите API-ключи

Создайте новые API-ключи в AACsearch:

# Создайте ключ поиска (публичный)
curl -X POST "https://app.aacsearch.com/api/v1/keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search API Key",
    "scope": "search",
    "indexes": ["products"]
  }'

# Результат:
# {
#   "key": "ss_search_...",
#   "keyHash": "..."
# }

Важно: API-ключ поиска (публичный) можно безопасно встраивать на клиент. Не используйте админ-ключи на клиенте.

Шаг 6: Обновите фронтенд

JavaScript

// Старый код Typesense
const typesense = new Typesense.SearchClient({
  nodes: [{
    host: 'localhost',
    port: 8108,
    protocol: 'http'
  }],
  apiKey: 'your_api_key',
  connectionTimeoutSeconds: 2
});

// Новый код AACsearch
const searchClient = new AACSearchClient({
  apiKey: 'ss_search_...',
  baseURL: 'https://app.aacsearch.com'
});

// Поиск
const results = await searchClient.search({
  indexSlug: 'products',
  query: 'кроссовки',
  filters: { category: 'обувь', price: { lte: 10000 } },
  limit: 20
});

Python

import aac_search

client = aac_search.AACSearchClient(
    api_key='ss_search_...',
    base_url='https://app.aacsearch.com'
)

results = client.search(
    index_slug='products',
    query='кроссовки',
    filters={'category': 'обувь', 'price': {'lte': 10000}},
    limit=20
)

for hit in results['hits']:
    print(hit['title'], hit['price'])

cURL

curl -X POST "https://app.aacsearch.com/api/v1/indexes/products/search" \
  -H "Authorization: Bearer ss_search_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "кроссовки",
    "filters": {"category": "обувь", "price": {"lte": 10000}},
    "limit": 20
  }'

Шаг 7: Переключитесь на новый эндпоинт

Обновите URL в приложении

// Раньше
const searchURL = 'http://localhost:8108/collections/products/documents/search';

// Теперь
const searchURL = 'https://app.aacsearch.com/api/v1/indexes/products/search';

Обновите виджет поиска

<!-- Старый Typesense виджет -->
<script src="https://cdn.jsdelivr.net/npm/typesense-instantsearch-adapter@2/dist/typesense-instantsearch-adapter.min.js"></script>

<!-- Новый AACsearch виджет -->
<div id="aac-search"></div>
<script 
  src="https://app.aacsearch.com/api/widget/widget.js"
  data-api-key="ss_search_..."
  data-index-slug="products"
  data-container="#aac-search">
</script>

Проверка миграции

  1. Количество документов: проверьте, что все документы загружены

    curl "https://app.aacsearch.com/api/v1/indexes/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

  2. Поиск работает: попробуйте поискать несколько товаров

    curl -X POST "https://app.aacsearch.com/api/v1/indexes/products/search" \
  -H "Authorization: Bearer ss_search_..." \
  -d '{"query": "кроссовки"}'

  3. Фильтры работают: проверьте фильтры по категориям и цене

  4. Производительность: сравните скорость старого и нового поиска

Откат на Typesense

Если возникли проблемы, вы можете вернуться на Typesense:

// Обновите URL обратно на Typesense
const searchURL = 'http://localhost:8108/collections/products/documents/search';

// Очистите кэш браузера (Ctrl+Shift+Delete)

Часто задаваемые вопросы

Q: Все ли документы загрузились?
A: Проверьте в панели AACsearch → Поиск → Статистика. Там должно быть столько же документов, сколько в Typesense.

Q: Почему поиск работает по-другому?
A: У AACsearch и Typesense разные алгоритмы ранжирования. Это нормально. Вы можете отрегулировать сортировку через настройки индекса.

Q: Нужна ли оптимизация?
A: AACsearch автоматически оптимизирует индексы. Вам не нужно ничего делать.

Q: Как быстро загружаются новые документы?
A: Новые документы индексируются в течение несколько секунд.

Q: Поддерживает ли AACsearch иерархические фильтры?
A: Да, используйте массивы строк для иерархических фильтров (например, ["Женская обувь", "Кроссовки"]).

Помощь и поддержка

С Meilisearch

Миграция с Meilisearch в AACsearch — экспорт индекса, маппинг схемы, перевод запросов.

Чек-лист миграции

Dry run, валидация, cutover, откат — чек-лист на день переключения.

On this page

Миграция из TypesenseОбзор миграцииШаг 1: Экспортируйте индекс из TypesenseШаг 2: Создайте индекс в AACsearchШаг 3: Импортируйте данныеШаг 4: Настройте параметры поискаФильтры (facets)СинонимыСортировка по релевантностиШаг 5: Обновите API-ключиШаг 6: Обновите фронтендJavaScriptPythoncURLШаг 7: Переключитесь на новый эндпоинтОбновите URL в приложенииОбновите виджет поискаПроверка миграцииОткат на TypesenseЧасто задаваемые вопросыПомощь и поддержка