Индексация кодовой базы

​

Как это работает

1. Парсинг кода — система анализирует код с помощью Tree-sitter и выделяет семантические блоки (функции, классы, методы)
2. Создание embeddings — каждый блок кода преобразуется в векторное представление с помощью AI моделей
3. Хранение векторов — векторы сохраняются в базе данных Qdrant для быстрого поиска по сходству
4. Инструмент поиска — Harvi Code получает доступ к инструменту codebase_search для умного поиска кода

​

Быстрый старт

​

Шаг 1: Выбери компоненты

1. Провайдер embeddings — для преобразования кода в векторы
2. Векторная база данных — для хранения и поиска векторов

​

Шаг 2: Настрой Qdrant (векторная БД)

​

Вариант A: Облачная установка (рекомендуется для начала) - БЕСПЛАТНО

1. Зарегистрируйся на Qdrant Cloud (есть бесплатный тариф)
2. Создай кластер
3. Скопируй URL и API ключ

​

Вариант B: Локальная установка - БЕСПЛАТНО

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant

services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
    volumes:
      - qdrant_storage:/qdrant/storage
volumes:
  qdrant_storage:

​

Шаг 3: Настрой провайдер embeddings

​

Google Gemini (рекомендуется) - БЕСПЛАТНО

1. Получи API ключ на Google AI Studio (сейчас бесплатно)
2. В настройках Harvi Code:
   • Provider: Google Gemini
   • API Key: Твой ключ из Google AI Studio

​

Шаг 4: Сохрани и запусти

1. Нажми Save и Start Indexing

• Жёлтый (Indexing): Идёт обработка файлов
• Зелёный (Indexed): Готово к поиску
• Красный (Error): Проверь раздел решения проблем

​

Управление индексатором

​

Иконка статуса

• 🟢 Зелёный: Indexed — индекс актуален и готов к поиску
• 🟡 Жёлтый: Indexing — система обрабатывает файлы (поиск доступен, но результаты могут быть неполными)
• 🔴 Красный: Error — произошла ошибка (проверь подключение к Qdrant или провайдеру embeddings)
• ⚪ Серый: Standby — индексатор ожидает настройки или отключён

​

Окно настроек

• Status: Детальное сообщение о текущем состоянии
• Setup: Основные поля для подключения к провайдеру embeddings и векторной БД
• Advanced Configuration: Тонкая настройка параметров поиска (порог сходства)
• Clear Index Data: Удаляет все данные из коллекции Qdrant и очищает локальный кэш (нельзя отменить)
• Save: Применяет изменения настроек

​

Поля настроек

​

Основные поля

• Embedder Provider: Выбор источника для генерации AI embeddings (OpenAI, Google Gemini, Ollama, OpenAI Compatible)
• API Key: Секретный ключ для аутентификации (для облачных провайдеров)
• Base URL: Endpoint для подключения к API (для Ollama и OpenAI Compatible)
• Model: Конкретная модель embeddings (размерность векторов показана рядом)
• Qdrant URL: Endpoint подключения к векторной БД (например, http://localhost:6333)
• Qdrant API Key: Ключ аутентификации для защищённого Qdrant (опционально)

​

Продвинутые настройки

• Search Score Threshold: Минимальный порог сходства для результатов поиска (0.0-1.0)
  • Низкий (0.15-0.3): Больше результатов, хорошо для исследования
  • Средний (0.4-0.5): Баланс точности и полноты (по умолчанию: 0.4)
  • Высокий (0.6-0.8): Только точные совпадения
• Maximum Search Results: Максимальное количество фрагментов кода в результатах одного поиска

​

Ключевые преимущества

• Семантический поиск: Находи код по смыслу, а не только по ключевым словам
• Улучшенное понимание AI: Harvi Code лучше понимает и работает с твоей кодовой базой
• Поиск по всему проекту: Ищи во всех файлах, а не только в открытых
• Распознавание паттернов: Находи похожие реализации и паттерны кода

​

Как обрабатываются файлы

​

Умный парсинг кода

1. Tree-sitter сначала: Для поддерживаемых языков использует AST парсинг для выделения семантических блоков
2. Поддержка Markdown: Индексирует Markdown файлы, используя заголовки как точки входа
3. Умный fallback: Для неподдерживаемых типов файлов использует разбиение по строкам

• Минимум: 100 символов
• Максимум: 1,000 символов
• Большие функции разбиваются на логических границах

​

Фильтрация файлов

• Файлы из .gitignore
• Файлы из .harviignore
• Бинарные файлы и изображения
• Файлы больше 1MB

​

Инкрементальные обновления

• Отслеживание файлов: Мониторит изменения в workspace в реальном времени
• Умные обновления: Обрабатывает только изменённые файлы
• Поддержка веток: Автоматически обрабатывает переключение веток Git
• Кэширование на основе хэшей: Избегает повторной обработки неизменённого контента

​

Лучшие практики

​

Эффективные запросы

• ❌ const getUser
• ✅ функция для получения пользователя из базы данных

• “middleware для аутентификации”
• “обработка ошибок для API запросов”
• “настройка подключения к базе данных”

​

Безопасность

• API ключи: Хранятся безопасно в зашифрованном хранилище VS Code
• Приватность кода: Только небольшие фрагменты кода отправляются для создания embeddings
• Локальная обработка: Весь парсинг происходит локально
• Контроль доступа: Учитывает права доступа к файлам и паттерны игнорирования

​

Решение проблем

​

Проблемы с подключением

• Убедись, что Qdrant запущен (docker ps для проверки)
• Проверь, что URL совпадает (по умолчанию: http://localhost:6333)
• Проверь firewall/сетевые политики
• Для облачных инстансов проверь URL и API ключ

• Перепроверь правильность API ключа
• Убедись, что ключ имеет необходимые права
• Для Ollama проверь, что сервис запущен

​

Ошибки формата API ключа

• Симптом: Ошибка упоминает “ByteString conversion”
• Причина: API ключ содержит недопустимые символы или скрытые пробелы
• Решение: Сгенерируй новый ключ и вставь его заново, убедившись в отсутствии лишних пробелов

​

Проблемы с моделями

• Для Google Gemini: Убедись, что имя модели правильное (например, text-embedding-004)
• Для других провайдеров: Проверь документацию для доступных моделей

​

Проблемы с индексацией

1. Сначала проверь проблемы с подключением
2. Кликни “Clear Index & Re-index” в настройках
3. Это решает проблемы с повреждённым кэшем или коллекцией

• Нормально для больших кодовых баз (10k+ файлов)
• Проверь, что .gitignore включает большие директории
• Рассмотри добавление паттернов в .harviignore

​

Использование поиска

• “Как обрабатывается аутентификация пользователя?”
• “Настройка подключения к базе данных”
• “Паттерны обработки ошибок”
• “Определения API endpoints”
• “Управление состоянием компонентов”

• Релевантные фрагменты кода
• Пути к файлам с номерами строк
• Оценки сходства
• Прямые ссылки для навигации

​

Приватность и безопасность данных

• Только небольшие фрагменты кода (100-1000 символов) отправляются для создания embeddings
• Embeddings — это односторонние математические представления
• Локальный парсинг означает, что полные файлы не покидают твою машину
• Используй Ollama для полностью офлайн работы

• Векторы хранятся в выбранном тобой инстансе Qdrant
• Ты контролируешь, где хранятся данные (локально/облако)
• Легко удалить: просто очисти индекс

​

Текущие ограничения

• Размер файла: Максимум 1MB на файл
• Внешние зависимости: Требуется провайдер embeddings + Qdrant
• Поддержка языков: Лучшие результаты с языками, поддерживаемыми Tree-sitter