Руководство по устранению неполадок

Распространённые проблемы и их решения для CodeGraph.

Содержание

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

Несовместимость версии DuckDB

Симптом:

duckdb.InvalidInputException: Catalog Error: ...DuckPGQ...

Решение:

CodeGraph требует duckdb>=1.4.4 для расширения DuckPGQ. Проверьте версию:

python -c "import duckdb; print(duckdb.__version__)"

# Обновите, если версия ниже 1.4.4
pip install "duckdb>=1.4.4"

CUDA не найдена

Симптом:

RuntimeError: CUDA not available

Решение:

# Проверка установки CUDA
nvidia-smi
nvcc --version

# Переустановка PyTorch с поддержкой CUDA
pip uninstall torch
pip install torch --index-url https://download.pytorch.org/whl/cu118

Не удалось подключиться к DuckDB

Симптом:

duckdb.IOException: Could not open file 'data/projects/postgres.duckdb'

Решение:

# Проверка существования файла
ls -la data/projects/postgres.duckdb

# Проверка прав доступа
chmod 644 data/projects/postgres.duckdb

# Проверка, не заблокирован ли файл другим процессом
lsof data/projects/postgres.duckdb  # Linux/Mac

Не удалось инициализировать ChromaDB

Симптом:

chromadb.errors.ChromaDBError: Collection not found

Решение:

# Проверка существования каталога chroma_db/ (НЕ chromadb_storage/)
ls -la chroma_db/

# Повторная инициализация при необходимости
python scripts/init_vector_store.py

Предупреждение: Никогда не удаляйте каталог chroma_db/. Он содержит 250K+ проиндексированных документов, и повторный импорт занимает значительное время.

Ошибки импорта

Симптом:

ModuleNotFoundError: No module named 'src'

Решение:

# Убедитесь, что вы находитесь в корне проекта
cd /path/to/codegraph

# Добавьте в PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Или установите в режиме разработки
pip install -e .

Проблемы с тестами

Ошибка импорта DuckDB с pytest

Симптом:

ImportError: DuckDB extension error when running pytest

Решение:

Всегда запускайте тесты из каталога tests/, а не из корня проекта:

# ПРАВИЛЬНО
pytest tests/ -v

# НЕПРАВИЛЬНО — вызывает ошибку импорта DuckDB
pytest .

Ошибка захвата вывода pytest на Windows

Симптом (Python 3.13 на Windows):

ValueError: I/O operation on closed file

Полный набор тестов падает с pytest 9.0.2 + Python 3.13 на Windows.

Решение:

# Используйте флаг -s для отключения захвата вывода
pytest tests/ -v -s

Запуск отдельных блоков тестов не затронут; проблема проявляется только при полном прогоне.

Проблемы с поставщиком LLM

Ошибка аутентификации GigaChat

Симптом:

401 Unauthorized: Invalid credentials

Решение:

# Проверка переменной окружения
echo $GIGACHAT_AUTH_KEY

# Установите, если отсутствует
export GIGACHAT_AUTH_KEY="your_key"

# Проверка в Python
python -c "import os; print(os.environ.get('GIGACHAT_AUTH_KEY', 'NOT SET'))"

Недостаточно памяти у локальной модели LLM

Симптом:

CUDA out of memory

Решение:

# Уменьшите количество слоёв в config.yaml → llm.local
llm:
  local:
    n_gpu_layers: 20  # Уменьшить с -1
    n_ctx: 4096       # Уменьшить размер контекста

Или используйте модель с меньшим квантованием:

# Используйте Q4_K_M вместо Q5_K_M

Время ожидания ответа LLM

Симптом:

TimeoutError: LLM did not respond within timeout

Решение:

Таймаут настраивается для каждого LLM-провайдера в config.yaml:

# Увеличьте таймаут для конкретного провайдера
llm:
  gigachat:
    timeout: 120  # секунд (по умолчанию: 60)
  yandex:
    timeout: 300  # секунд (по умолчанию: 180)

Проблемы с запросами

Результаты не найдены

Симптом:

No methods found matching query

Решения: 1. Проверьте орфографию — имена методов чувствительны к регистру 2. Используйте частичное совпадение — попробуйте *Transaction* вместо CommitTransaction 3. Проверьте базу данных — убедитесь, что данные существуют: sql SELECT COUNT(*) FROM nodes_method WHERE full_name LIKE '%Transaction%';

Медленная работа запросов

Симптом: Запрос выполняется более 10 секунд

Решения:

# Уменьшите объём поиска в config.yaml
retrieval:
  top_k_qa: 3      # Уменьшить значение по умолчанию

# Переключитесь на режим только векторного поиска (быстрее гибридного)
workflows:
  handlers:
    retrieval_weights:
      mode: vector_only   # Вместо "hybrid"

Некорректные результаты

Симптом: Ответы не соответствуют ожидаемым

Решения: 1. Уточните вопрос — будьте более конкретны 2. Проверьте домен — убедитесь, что выбран правильный домен 3. Проверьте эмбеддинги — пересоздайте, если повреждены: bash python -m src.cli.import_commands full --path ./source --language c

Проблемы с GoCPG

Ошибка парсинга GoCPG

Симптом:

Error: failed to parse source files

Решение:

# Проверьте, что GoCPG собран с CGO
CGO_ENABLED=1 go build -o gocpg ./cmd/gocpg

# Проверьте доступные модули анализа
./gocpg frontends

# Повторите парсинг с подробным логированием
./gocpg parse --input=/path/to/source --output=data/projects/postgres.duckdb --lang=c --verbose

Проблемы с памятью

Недостаточно памяти во время обработки

Симптом:

MemoryError: Unable to allocate

Решения:

# Уменьшите размер пакетов в config.yaml
batch_processing:
  extraction_default_limit: 500   # Уменьшить значение по умолчанию
  chromadb_batch: 100             # Уменьшить размер пакета ChromaDB

Нехватка памяти при бенчмарках

Симптом: Запуск гипотез или бенчмарков потребляет всю память

Решение:

# Запускайте бенчмарки пакетами
python -m src.cli hypothesis run --max-questions 3 --offset 0
python -m src.cli hypothesis run --max-questions 3 --offset 3

Высокое использование памяти

Симптом: Система становится неотзывчивой

Решения:

# Мониторинг использования памяти
watch -n 1 'free -h'

# Очистка кешей запросов
python -c "from src.optimization.query_cache import QueryCache; QueryCache().clear()"

# ChromaDB по умолчанию хранит данные на диске (каталог chroma_db/)
# Проверьте его размер: du -sh chroma_db/

Проблемы с API и MCP

Порт уже используется

Симптом:

OSError: [Errno 98] Address already in use

Решение:

# Проверьте, что использует порт
lsof -i :8000  # Порт API по умолчанию
lsof -i :27495 # Порт MCP по умолчанию

# Завершите процесс или используйте другой порт
uvicorn src.api.main:app --port 8001
python -m src.mcp --port 27496

JWT-секрет не настроен

Симптом:

ValueError: API_JWT_SECRET must be at least 64 characters

Решение:

# Сгенерируйте и установите JWT-секрет (64+ символов)
export API_JWT_SECRET=$(python -c "import secrets; print(secrets.token_hex(64))")

Отладка

Включение отладочного логирования

Установите уровень отладки в вашем скрипте:

import logging
logging.basicConfig(level=logging.DEBUG)

Или настройте логирование API-запросов в config.yaml:

security:
  logging:
    request_logging: true
    audit_logging: true
    log_request_body: true

Проверка состояния компонентов

# Диагностический скрипт
import duckdb
from src.services.cpg import CPGQueryService
from src.retrieval.vector_store_real import VectorStoreReal

# Проверка DuckDB
cpg = CPGQueryService()
conn = cpg._get_connection()
result = conn.execute("SELECT COUNT(*) FROM nodes_method").fetchone()
print(f"Методов в БД: {result[0]}")

# Проверка векторного хранилища
vs = VectorStoreReal()
vs.initialize_collections()  # Обязательно перед обращением к коллекциям
print(f"QA-документов: {vs.qa_collection.count()}")

# Проверка LLM
from src.llm.llm_interface_compat import get_llm
llm = get_llm()
print(f"LLM: {type(llm).__name__}")

Генерация отчёта об отладке

python -c "
import sys
import platform

print('=== Информация о системе ===')
print(f'Python: {sys.version}')
print(f'Платформа: {platform.platform()}')

print('\n=== CUDA ===')
try:
    import torch
    print(f'PyTorch: {torch.__version__}')
    print(f'CUDA доступна: {torch.cuda.is_available()}')
    if torch.cuda.is_available():
        print(f'Версия CUDA: {torch.version.cuda}')
        print(f'GPU: {torch.cuda.get_device_name(0)}')
except ImportError:
    print('PyTorch не установлен')

print('\n=== Зависимости ===')
import duckdb
print(f'DuckDB: {duckdb.__version__}')

import chromadb
print(f'ChromaDB: {chromadb.__version__}')
"

Получение помощи

Если проблемы сохраняются:

  1. Проверьте stderr — логирование по умолчанию выводится в stderr (без файла логов)
  2. Изучите существующие обращения в репозитории
  3. Создайте новое обращение, указав: - Сообщение об ошибке - Шаги для воспроизведения - Вывод отладочного отчёта - config.yaml (без конфиденциальных данных)

Дальнейшие шаги