Шаг 1 (Утро: Спокойствие и первичная диагностика). Первое правило при любой ошибке — не впадать в панику. Зафиксируйте точное сообщение об ошибке. Weaviate выдает ошибки через REST API (HTTP статусы 4xx/5xx) и в логах. Скопируйте полный текст. Определите контекст: при каком действии возникает ошибка? Создание схемы? Добавление данных? Поисковый запрос? Запуск модуля (например, `text2vec-transformers`)? Откройте документацию Weaviate и раздел "Troubleshooting". Многие распространенные ошибки (например, `422: vector search: no vector index found for class 'Article'`) уже описаны там с решениями.
Шаг 2 (Сбор информации о окружении). Без точных данных об окружении дальнейшее движение вслепую. За 15 минут соберите ключевую информацию: версия Weaviate (запрос `GET /v1/meta`); используемые модули и их версии (конфигурация при запуске); способ развертывания (Docker Compose, Kubernetes с Helm, standalone); объем оперативной памяти и CPU, доступные контейнеру/поду; логи Weaviate (команда `docker logs ` или `kubectl logs `). Особое внимание уделите логам за последние 5-10 минут до ошибки. Ищите ключевые слова: `panic`, `error`, `failed`, `timeout`.
Шаг 3 (Анализ и классификация ошибки). Собранные данные позволяют классифицировать проблему. Основные категории:
- Ошибки схемы (Schema): несоответствие типов данных, конфликт имен классов или свойств, неправильная конфигурация векторного индекса (например, distance metric).
- Ошибки данных (Data): проблемы при добавлении или обновлении объектов, часто связанные с модулями векторного преобразования (например, сбой эмбеддинга текста).
- Ошибки запросов (Query): синтаксические ошибки в GraphQL, неверные фильтры, таймауты при сложных агрегациях.
- Ошибки модулей (Modules): модули `text2vec-*`, `qna-*`, `sum-*` не запустились, требуют GPU или имеют проблемы с загрузкой моделей.
- Ошибки инфраструктуры: нехватка памяти (OOM Killer), нехватка дискового пространства, проблемы с сетью между модулями.
Для ошибок схемы: используйте запрос `GET /v1/schema` для проверки текущей схемы. Сравните ее с той, которую вы пытаетесь создать. Помните, что некоторые изменения схемы (например, изменение типа свойства) требуют полного пересоздания класса. План на такой случай должен быть: 1) экспорт данных, 2) удаление класса, 3) создание исправленной схемы, 4) импорт данных.
Для ошибок данных: проверьте формат отправляемых JSON-объектов. Убедитесь, что для свойств, требующих векторы, вы либо предоставляете вектор сами, либо активирован соответствующий модуль для его генерации. Проверьте лог модуля векторного преобразования. Если используется `text2vec-openai`, убедитесь в валидности API-ключа и доступности эндпоинта.
Для ошибок запросов: упростите запрос GraphQL до базового `{ Get { ClassName { property } } }`. Если он работает, постепенно усложняйте, добавляя фильтры (`where`), векторный поиск (`nearVector`, `nearText`), пагинацию. Используйте встроенный интерфейс GraphQL Weaviate (доступен по `http://localhost:8080/v1/graphql` в режиме разработки) для валидации запросов.
Для ошибок модулей: проверьте логи конкретного модуля. Убедитесь, что образ модуля совместим с версией Weaviate. Проверьте переменные окружения модуля (например, `ENABLE_MODULES` в основном контейнере, `TRANSFORMERS_INFERENCE_API` для текстового модуля). Для модулей, требующих модели, убедитесь в наличии сетевого доступа для их загрузки или предзагрузите модели в образ.
Для инфраструктурных ошибок: мониторьте потребление ресурсов. Увеличьте лимиты памяти в Docker Compose или Helm values. Для продакшн-нагрузок не используйте `vectorIndexType: "hnsw"` с `flat` поиском без понимания компромиссов скорости/памяти.
Шаг 5 (Верификация и профилактика). После применения исправления обязательно протестируйте операцию, которая вызывала ошибку. Затем проведите базовый smoke-тест: создание схемы, добавление объекта, простой поиск. Чтобы предотвратить повторение, задокументируйте инцидент: причина, решение, конфигурационные изменения. Рассмотрите возможность добавления health-чеков для Weaviate в вашу систему мониторинга (Prometheus метрики доступны по умолчанию). Настройте алерты на высокое потребление памяти и ошибки 5xx.
К концу дня, следуя этой структурированной инструкции, вы не только решите конкретную проблему, но и создадите для себя и команды четкий алгоритм действий на будущее, значительно снизив время простоя и стресс при работе со сложной, но мощной системой, такой как Weaviate.
Комментарии (7)