Создание графа знаний из кода с помощью Graphify

Создание графа знаний из кода с помощью Graphify

Разбираем Graphify: инструмент для построения графа знаний из кодовой базы, документации и схем SQL без использования векторных хранилищ.

Как Graphify превращает код в граф знаний

Как Graphify превращает код в граф знаний

Когда мы говорим об анализе кодовой базы, большинство современных решений предлагают использовать RAG (Retrieval-Augmented Generation) с векторными базами данных. Это работает, но часто превращает поиск по коду в лотерею: модель находит похожие по смыслу куски текста, но совершенно упускает структурные связи. Если функция calculate_total вызывает метод apply_discount, векторный поиск может их не связать, если в их описании нет общих слов.

Graphify работает иначе. Вместо того чтобы превращать код в набор абстрактных векторов, он строит явную карту зависимостей.

Принцип работы на основе AST

В основе Graphify лежит использование Abstract Syntax Tree (AST) — абстрактного синтаксического дерева. Если упростить, то AST — это структурное представление исходного кода, где каждый узел дерева соответствует конструкции языка: объявлению функции, циклу, переменной или импорту.

Процесс превращения кода в граф выглядит следующим образом:

1. Парсинг: Инструмент проходит по файлам и с помощью парсеров (например, на базе tree-sitter) строит AST для каждого файла.
2. Извлечение сущностей: Из дерева вычленяются ключевые объекты: классы, методы, интерфейсы, типы данных и схемы таблиц SQL.
3. Построение связей: На этом этапе происходит самое важное. Graphify анализирует не только текст, но и то, как узлы связаны между собой. Если в файле auth.py вызывается класс из models.py, в графе создаётся направленное ребро AUTH_SERVICE -> USER_MODEL.

С практической точки зрения это даёт ту самую предсказуемость, которой не хватает векторным методам. Когда AI-агент запрашивает контекст, он получает не «похожие куски кода», а точную цепочку вызовов. Это критически важно, если вы занимаетесь реверс-инжинирингом с помощью AI-агентов, где понимание иерархии и связей важнее, чем семантическая близость слов.

Для конфигурации процесса анализа можно использовать файл graphify.yaml. Пример базовой настройки для проекта на Python и PostgreSQL:

yamlКопировать
# Конфигурация Graphify для анализа проекта
project:
  name: "my-backend-service"
  root: "./src"

parsers:
  python:
    enabled: true
    include: ["**/*.py"]
  sql:
    enabled: true
    include: ["./migrations/*.sql"]

graph:
  # Указываем, какие типы связей нам важны
  extract_relations:
    - function_calls
    - class_inheritance
    - sql_foreign_keys
    - variable_assignments

Почему отсутствие векторного хранилища — это плюс

Обычно для работы с контекстом в AI-системах разворачивают векторные БД (Chroma, Pinecone или Weaviate). Это добавляет сложности: нужно следить за индексами, управлять эмбеддингами и, что самое неприятное, бороться с «галлюцинациями» поиска, когда модель находит не то, что нужно.

Graphify сознательно отказывается от векторного хранилища в пользу графовой структуры. У этого подхода есть три весомых преимущества:

1. Точность связей. В графе связь между объектами — это факт, а не вероятность. Если в коде есть зависимость, она будет отражена в графе со 100% точностью. Это избавляет от проблем, когда при оптимизации работы AI-агентов агент начинает «фантазировать» о несуществующих методах.
2. Низкие накладные расходы. Вам не нужно держать в памяти тяжелые индексы векторов. Граф — это, по сути, набор узлов и ребер, который можно эффективно обходить стандартными алгоритмами обхода графа (BFS/DFS). Это позволяет запускать анализ даже на небольших домашних серверах или в изолированных средах.
3. Прозрачность (Explainability). Если агент выдал странный ответ, вы можете проследить путь по графу и понять, на основе каких именно связей был сделан вывод. В векторном поиске этот путь — «чёрный ящик».

Если вы используете инструменты вроде Claude Code для глубокого анализа, наличие структурированного графа вместо разрозненных векторов превращает работу агента из угадывания в осознанное навигаторство по коду. Вместо того чтобы искать «что-то про авторизацию», агент может спросить: «Покажи мне все функции, которые напрямую или косвенно взаимодействуют с таблицей users через ORM».

Возможности анализа документации и схем

Обработка SQL-схем и конфигурационных файлов

Когда мы говорим о понимании кодовой базы, часто забываем, что логика приложения неразрывно связана со структурой данных. Если AI-агент не понимает связей между таблицами, он будет предлагать решения, которые теоретически верны, но практически ломают консистентность базы.

Graphify решает эту проблему через глубокий анализ AST (Abstract Syntax Tree) и парсинг SQL-дампов. Вместо того чтобы просто «скармливать» текст модели, инструмент выстраивает явные связи: внешние ключи (Foreign Keys), индексы и ограничения (Constraints). Это позволяет создать предсказуемую карту зависимостей.

С практической точки зрения, это особенно полезно при реверс-инжиниринге с помощью AI-агентов, когда документации нет, а есть только развернутая база. Вы можете скормить инструменту .sql файл, и он превратит его в граф, где узлами будут таблицы, а ребрами — связи между ними.

Пример того, как Graphify может интерпретировать схему для построения графа:

sqlКопировать
-- Входной файл schema.sql
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE orders (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    amount DECIMAL(10, 2)
);

В графе знаний это превратится не в набор строк, а в структуру, где узел orders имеет направленную связь к узлу users. Если вы используете Claude Code для анализа проекта, наличие такой карты позволяет агенту не гадать, откуда приходят данные, а точно знать путь запроса.

То же самое касается конфигурационных файлов. Разбор docker-compose.yml или файлов настроек Nginx позволяет Graphify понять топологию сети: какие контейнеры общаются друг с другом и какие порты проброшены. Это критически важно для понимания инфраструктурных зависимостей.

Интеграция PDF и текстовой документации

Код — это только половина правды. Вторая половина обычно спрятана в README, Confluence или PDF-спецификациях, которые никто не любит читать целиком. Проблема классических RAG-систем (Retrieval-Augmented Generation) в том, что они работают с «кусками» текста, часто теряя контекст между абзацами.

Graphify подходит к документации иначе. Вместо того чтобы просто нарезать текст на векторы, он пытается извлечь сущности и их отношения. Если в PDF-файле написано: «Сервис авторизации использует Redis для кэширования сессий», инструмент создаст связь между сущностями Auth Service и Redis.

Для эффективной работы с документацией важно правильно подготовить входные данные. Если вы хотите, чтобы граф был максимально точным, рекомендую придерживаться следующих правил при подготовке текстовых файлов:

1. Структурированность: Используйте четкие заголовки и списки.
2. Терминологическая строгость: Избегайте двусмысленностей. Если в коде переменная называется user_session_id, в документации не стоит называть её «ключом входа».
3. Связанность: Упоминайте компоненты системы так, как они описаны в коде.

Для автоматизации процесса обработки можно использовать CLI-интерфейс Graphify. Например, чтобы проиндексировать папку с документацией и SQL-схемами:

bashКопировать
# Команда для построения графа из директории docs и sql-дампов
graphify build --input ./project_root --include "*.sql,*.md,*.pdf" --output ./knowledge_graph

Такой подход позволяет значительно расширить набор навыков для работы с AI-агентами. Агент, опираясь на такой граф, не просто ищет похожие куски текста, а понимает архитектурную логику: «Я вижу, что этот метод в коде работает с таблицей orders, которая, согласно PDF-спецификации, является критическим узлом для биллинга». Это превращает хаотичный поиск в осмысленный анализ.

Интеграция с AI-инструментами разработки

Использование в Claude Code и Cursor

Главная проблема при работе с AI-агентами в больших репозиториях — это «галлюцинации» из-за неполного контекста. Когда вы просите Claude Code отрефакторить метод, он видит только текущий файл, но не знает, как этот метод влияет на зависимости в других модулях. Graphify решает это, предоставляя агенту не просто куски текста, а структурную карту связей.

В Claude Code интеграция происходит через передачу экспортированного графа в качестве контекстного файла. Вместо того чтобы скармливать агенту сотни файлов, вы даёте ему сжатый, но информативный knowledge_graph.json. Это значительно повышает предсказуемость ответов.

Для подготовки контекста сначала сформируйте граф в корне вашего проекта:

bashКопировать
# Генерация графа знаний для текущей директории
graphify build --output ./context/graph.json --format json

После этого вы можете использовать этот файл в сессии Claude Code. С практической точки зрения, эффективнее всего подавать граф через системный промпт или при инициализации сессии, чтобы агент понимал топологию проекта.

Если вы используете Cursor, подход будет иным. Поскольку Cursor опирается на собственный индекс, Graphify здесь выступает как инструмент для создания «внешней памяти». Вы можете добавить путь к сгенерированному JSON-файлу в .cursorrules. Это позволит модели при каждом запросе обращаться к структуре связей, которую вы подготовили.

Пример настройки .cursorrules для работы с графом:

markdownКопировать
# Context Integration
Always refer to the project structure defined in ./context/graph.json.
When analyzing dependencies or data flow, use the nodes and edges 
provided in the graph to ensure architectural consistency.

Такой подход помогает избежать типичных ошибок, когда агент предлагает изменения, нарушающие инкапсуляцию или логику работы БД. Подробнее о том, как правильно готовить контекст для подобных задач, я писал в материале Ponytail: оптимизация работы AI-агентов.

Подключение к Gemini CLI

Работа с Gemini через командную строку (CLI) требует ещё более точного управления токенами. В отличие от чат-интерфейсов, где можно просто «прикрепить файл», в CLI-инструментах важно подавать только ту информацию, которая критична для решения конкретной задачи.

Graphify позволяет фильтровать граф, оставляя только нужные ветки (например, только связи SQL-схем и моделей Python), что делает интеграцию с Gemini максимально экономной.

Чтобы передать граф в Gemini CLI, лучше всего использовать пайплайн. Сначала мы извлекаем подграф, относящийся к конкретному модулю, а затем направляем его на вход утилите.

Предположим, нам нужно проанализировать модуль обработки платежей:

bashКопировать
# Извлекаем связи только для модуля 'payments' и передаем в Gemini
graphify extract --module payments --format json | gemini-cli ask "Проанализируй зависимости этого модуля и найди потенциальные узкие места в транзакциях"

Если ваша задача связана с глубоким анализом бинарных файлов или сложной логики, где требуется понимание низкоуровневых связей, рекомендую ознакомиться с моим разбором темы Реверс-инжиниринг с помощью AI-агентов в REA.

Для стабильной работы такой связки важно следить за тем, чтобы формат вывода Graphify соответствовал ожиданиям парсера Gemini. Если вы строите автоматизированный пайплайн, всегда проверяйте валидность JSON перед отправкой:

bashКопировать
graphify build --output graph.json && jq empty graph.json && gemini-cli ...

Здесь jq empty выступает в роли простой проверки: если файл повреждён, команда завершится с ошибкой, не тратя ваши токены на отправку мусора. Это обеспечивает ту самую предсказуемость, которая необходима при автоматизации инфраструктурных задач. Для тех, кто только начинает осваивать подобные инструменты, полезно будет изучить набор навыков для работы с AI-агентами.

Практическое применение в инженерных задачах

Ускорение онбординга в новый проект

Когда я в первый раз пришёл в проект с монолитом на несколько сотен тысяч строк кода, главной проблемой была не синтаксическая сложность, а отсутствие контекста. Вы понимаете, как работает функция, но не понимаете, почему она вызывает именно этот сервис и какие побочные эффекты это вызовет в базе данных. Традиционные методы — чтение документации и попытки проследить цепочки вызовов вручную — занимают недели.

Graphify меняет подход: вместо того чтобы изучать файлы по отдельности, вы изучаете связи. Инструмент строит абстрактное синтаксическое дерево (AST) и связывает его с описанием схем БД. С практической точки зрения это позволяет быстро составить карту зависимостей.

Представьте, что вам нужно понять, как изменение в одной таблице повлияет на логику приложения. Вместо бесконечного поиска по репозиторию, вы можете использовать Graphify для генерации графа, который покажет путь от SQL-схемы до конкретных методов в коде. Это напоминает реверс-инжиниринг с помощью AI-агентов, но применительно к легитимному исходному коду, а не к бинарным файлам.

Для начала работы достаточно указать путь к исходникам и конфигурационным файлам. Пример базового запуска для анализа Python-проекта с PostgreSQL:

bashКопировать
# Запуск анализатора для указанной директории
graphify analyze ./src --db-schema ./migrations/schema.sql --output ./knowledge-graph.json

После генерации графа вы получаете структурированный файл, который можно подать на вход AI-агенту. Это делает процесс обучения предсказуемым: агент не будет галлюцинировать о несуществующих связях, так как он опирается на жесткую структуру графа, а не на вероятностное предсказание следующего токена. Для более эффективного взаимодействия с такими системами рекомендую изучить материал про оптимизацию работы AI-агентов.

Поиск связей в сложных микросервисных архитектурах

В распределённых системах проблема «разрыва контекста» стоит ещё острее. Каждый микросервис может быть написан на своём языке, иметь свою БД и свои способы взаимодействия. Когда происходит сбой, часто трудно понять, какой именно сервис стал первопричиной (root cause), если ошибка пробросилась через пять слоёв.

Graphify позволяет объединить разрозненные части в единую модель знаний. Если мы рассматриваем архитектуру, где сервисы общаются через API или очереди, мы можем добавить описания этих интерфейсов в граф. Это позволяет увидеть не только внутреннюю логику каждого сервиса, но и топологию всей системы.

С точки зрения системного инженера, это превращает «черный ящик» в прозрачную схему. Если вы используете инструменты вроде Claude Code, наличие такого графа позволяет агенту не просто писать код, а понимать архитектурные ограничения.

Пример того, как можно описать связи между сервисами в конфигурационном файле для Graphify, чтобы расширить граф знаниями об инфраструктуре:

yamlКопировать
# config.yaml для расширения контекста графа
project_name: "payment-system"
services:
  - name: "order-service"
    path: "./services/orders"
    dependencies:
      - service: "payment-gateway"
        type: "grpc"
        endpoint: "payments.internal:50051"
  - name: "payment-gateway"
    path: "./services/payments"
    db_connection: "postgres://user:pass@db-host:5432/payments"

Такой подход позволяет реализовать глубокий анализ: например, вы можете спросить систему: «Какие сервисы затронет изменение типа поля user_id в таблице transactions?». Благодаря тому, что Graphify работает с AST и явными связями, ответ будет базироваться на реальных путях вызовов, а не на предположениях. Это критически важно для поддержания стабильности, когда вы расширяете набор навыков для работы с AI-агентами в рамках вашей команды.

Заключение

Итоговая оценка инструмента

Graphify — это не универсальная замена полноценным RAG-системам (Retrieval-Augmented Generation), а узкоспециализированный инструмент для тех, кому важна структурная точность. Если векторные базы данных работают с семантическим сходством, то Graphify работает с логическими связями. Это принципиально другой подход к анализу.

С практической точки зрения, инструмент показывает себя лучше всего в задачах, где нельзя допускать «галлюцинаций» из-за неверной интерпретации связей. Например, когда вам нужно понять, как изменение в одной таблице PostgreSQL повлияет на цепочку вызовов в Python-сервисе. Благодаря использованию AST (Abstract Syntax Tree), граф получается предсказуемым: вы видите не «похожие на вопрос куски текста», а реальную топологию вашего приложения.

Однако стоит учитывать ограничения. Graphify не заменит глубокое обучение, если ваша задача — поиск по смыслу в огромном массиве неструктурированных логов. Он предназначен для работы с кодом и схемами, где структура важнее контекста.

Когда стоит внедрять

Я рекомендую использовать Graphify в следующих сценариях:

1. Onboarding новых разработчиков. Вместо того чтобы заставлять человека читать сотни файлов, можно дать ему визуальную карту зависимостей.
2. Анализ legacy-кода. Когда документация устарела, а код превратился в «спагетти», построение графа помогает найти точки входа и критические узлы. Это перекликается с методами, которые мы обсуждали в статье про реверс-инжиниринг с помощью AI-агентов.
3. Подготовка контекста для AI-агентов. Если вы строите автоматизированную систему, ей нужно давать не весь репозиторий, а только релевантные узлы графа. Это помогает избежать перегрузки контекстного окна и делает работу агента более осмысленной, что критически важно для оптимизации работы AI-агентов.

Практические рекомендации по развертыванию

Чтобы получить качественный результат, не стоит скармливать инструменту всё подряд. Начните с малого.

Во-первых, убедитесь, что ваши SQL-схемы и конфигурационные файлы имеют четкую структуру. Во-вторых, если вы планируете использовать это в связке с инструментами вроде Claude Code, настройте предварительную фильтрацию файлов.

Для базового запуска в Docker-окружении (чтобы не засорять основную систему зависимостями) используйте следующий подход:

dockerfileКопировать
# Пример запуска Graphify в изолированном контейнере
FROM python:3.11-slim

WORKDIR /app

# Копируем зависимости и исходный код
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# Запускаем процесс построения графа
# Указываем путь к директории с кодом и выходной файл для графа
CMD ["python", "graphify_cli.py", "--source", "./src", "--output", "./graph_data.json"]

Если вы планируете интегрировать полученные данные в свои пайплайны, лучше всего экспортировать их в JSON-формате. Это обеспечит максимальную предсказуемость при последующей обработке вашими скриптами или агентами.

Для тех, кто только начинает осваивать работу с автономными системами, рекомендую изучить набор навыков для работы с AI-агентами, чтобы понимать, как правильно подавать данные из графа в LLM.

FAQ

Как Graphify анализирует зависимости?

Инструмент не просто ищет текстовые упоминания функций, а строит связи на основе абстрактного синтаксического дерева (AST). Если мы говорим о коде, Graphify разбирает структуру файлов, чтобы понять, какая функция вызывает другую, как связаны классы и какие модули зависят от конкретных библиотек.

Для SQL-схем процесс похожий: инструмент анализирует связи FOREIGN KEY, выстраивая граф отношений между таблицами. Это позволяет получить ту самую предсказуемость связей, которой часто не хватает при использовании обычного семантического поиска. Вместо того чтобы гадать, почему векторный поиск выдал нерелевантный кусок кода, вы работаете с жесткой логической структурой.

Такой подход критически важен, если вы используете набор навыков для работы с AI-агентами, где агенту нужно точно понимать контекст вызова метода, а не просто «похожесть» слов.

Нужно ли разворачивать отдельную базу данных?

Нет, в этом и заключается одно из главных преимуществ Graphify. В отличие от классических RAG-систем (Retrieval-Augmented Generation), которые требуют развёртывания векторных хранилищ вроде Chroma или Pinecone, Graphify работает иначе.

Он формирует граф знаний и предоставляет его через API или локальные файлы. Это избавляет от необходимости поддерживать дополнительный слой инфраструктуры и следить за консистентностью векторов. С практической точки зрения, это делает процесс анализа гораздо легче: вы можете запустить инструмент прямо в своей домашней лаборатории на небольшом устройстве, не выделяя под базу данных гигабайты оперативной памяти.

Если вы уже настраивали инфраструктуру для работы с Claude Code, то заметите, что Graphify вписывается в этот процесс как дополнительный аналитический модуль, а не как тяжеловесный сервис.

Какие типы файлов поддерживает инструмент?

На текущий момент Graphify ориентирован на три основных типа данных, которые составляют костяк любого проекта:

1. Исходный код: Основной упор сделан на языки с развитой поддержкой AST (Python, JavaScript/TypeScript, Go). Инструмент вытягивает не только определения функций, но и их взаимосвязи.
2. Документация: Markdown и текстовые файлы. Это позволяет связать технические описания с конкретными участками кода.
3. Схемы баз данных: SQL-дампы или файлы миграций. Это критично для понимания структуры данных, с которыми работает приложение.

Для управления процессом анализа используется конфигурационный файл. Например, чтобы ограничить область сканирования только нужными директориями, отредактируйте graphify.config.json:

jsonКопировать
{
  "include": ["src/**/*.ts", "docs/**/*.md", "migrations/*.sql"],
  "exclude": ["node_modules", "dist", "tests"],
  "parser_options": {
    "strict_mode": true
  }
}

Такой строгий подход к выбору файлов помогает избежать «шума» в графе, когда в него попадают сторонние библиотеки или скомпилированные артефакты, что часто случается при оптимизации работы AI-агентов.

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

Чем Graphify отличается от обычного векторного поиска?

Векторный поиск ищет семантическую близость, то есть фрагменты кода, которые похожи по смыслу или терминологии. Graphify же фокусируется на структурных связях, используя AST для выявления реальных зависимостей между объектами. С практической точки зрения это означает, что вы получите точную цепочку вызовов функций или связей между таблицами SQL, а не просто набор похожих по описанию кусков текста.

Можно ли использовать Graphify для анализа SQL-схем?

Да, инструмент поддерживает извлечение сущностей из SQL-схем и построение связей между ними. Это позволяет объединить логику приложения, описанную в коде, с архитектурой базы данных в едином графе знаний. В результате AI-агент сможет понимать, как конкретный метод в Python-коде влияет на структуру данных в определённой таблице.

Насколько точно инструмент определяет связи между файлами?

Точность напрямую зависит от качества парсинга через tree-sitter, который позволяет корректно интерпретировать синтаксис различных языков. Поскольку Graphify строит граф на основе явных объявлений и вызовов, а не на основе вероятностного сходства слов, вероятность ошибки в определении зависимости между модулями минимальна. Это обеспечивает ту самую предсказуемость, которая критически важна при работе с крупными кодовыми базами.

Требуется ли разворачивать отдельную векторную базу данных?

Нет, одно из ключевых преимуществ Graphify заключается в отсутствии необходимости использовать векторные хранилища. Инструмент работает со структурными данными напрямую, что упрощает архитектуру системы и снижает накладные расходы на инфраструктуру. Вы получаете карту зависимостей, готовую к передаче в контекст языковой модели без этапа индексации векторов.