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

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

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

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

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

Когда мы говорим о работе ИИ-агентов с кодовой базой, основная проблема заключается в потере контекста. Традиционные RAG-системы (Retrieval-Augmented Generation) работают с «кусками» текста, которые часто разрывают логические связи: функция может ссылаться на класс, который оказался в другом чанке, и агент просто не поймёт, как они связаны. Graphify решает эту задачу иначе, создавая не просто набор эмбеддингов, а полноценную карту зависимостей.

Принцип работы детерминированного AST-парсинга

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

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

1. Парсинг: Инструмент проходит по файлам и строит AST для каждого языка, который он поддерживает.
2. Извлечение сущностей: Из дерева вычленяются узлы — классы, интерфейсы, переменные и их атрибуты.
3. Построение связей: На этом этапе формируются ребра графа. Если функция calculate_total вызывает метод get_price у объекта класса Order, в графе знаний появляется прямая связь между этими узлами.

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

Пример того, как Graphify может интерпретировать простую структуру на Python:

pythonКопировать
# Исходный код
class Database:
    def connect(self):
        pass

class App:
    def __init__(self, db: Database):
        self.db = db

    def run(self):
        self.db.connect()

В графе знаний это превратится в набор узлов Database, App, connect, run и связей:

• App $\to$ has_attribute $\to$ db
• db $\to$ is_instance_of $\to$ Database
• App.run $\to$ calls $\to$ Database.connect

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

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

Большинство современных решений для работы с LLM полагаются на векторные базы данных. Идея понятна: превратить текст в вектор (набор чисел) и искать ближайшие по смыслу векторы. Но у этого подхода есть фундаментальный изъян при работе с кодом — потеря структурной логики. Векторное сходство хорошо находит «похожие» куски кода, но оно плохо справляется с поиском «связанных» кусков.

Graphify сознательно отказывается от обязательного использования векторных хранилищ в пользу графовых структур. Это даёт три ключевых преимущества:

1. Точность связей (Precision). Векторный поиск может вернуть функцию, которая выглядит похоже, но не имеет отношения к текущему контексту. Граф же выдаёт только те элементы, которые действительно связаны в коде.
2. Снижение галлюцинаций. Когда агент получает контекст в виде графа, он видит реальную топологию проекта. Это минимизирует ситуации, когда модель пытается вызвать несуществующий метод или предполагает наличие зависимости, которой нет.
3. Экономия ресурсов. Вам не нужно разворачивать тяжеловесные векторные БД и тратить токены на избыточную индексацию всего подряд. Вы работаете со структурой, которая уже содержит в себе смысл.

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

Для интеграции Graphify в существующий рабочий процесс (например, в рамках использования Omnara), достаточно настроить конфигурацию путей к исходникам:

yamlКопировать
# Пример конфигурации graphify.yaml
project:
  name: "my-backend-service"
  paths:
    - "./src"
    - "./migrations"
  languages:
    - python
    - sql
  output:
    format: "json-graph"
    destination: "./knowledge-base/graph.json"

В итоге вместо «облака смыслов» мы получаем строгую математическую модель проекта, которая позволяет агентам перемещаться по коду так же уверенно, как это делает опытный инженер.

Возможности анализа различных типов данных

Работа с исходным кодом и конфигурациями

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

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

Инструмент одинаково хорошо справляется и с конфигурационными файлами. Например, при анализе docker-compose.yml или манифестов Kubernetes, Graphify восстанавливает зависимости между сервисами, сетями и томами. Это позволяет создать карту инфраструктуры, где каждый контейнер — это узел с чётко прописанными связями.

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

bashКопировать
# Запуск анализа директории с исходным кодом
graphify analyze ./my-project --output ./knowledge-graph

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

Интеграция SQL-схем и PDF-документации

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

Когда вы подаёте на вход .sql файл с дампом структуры (DDL), инструмент строит граф отношений. Это позволяет ИИ-агенту не гадать, к какой таблице относится поле user_id, а точно знать, что оно является FOREIGN KEY, ссылающимся на таблицу users. Такая предсказуемость критична, если вы строите систему управления данными через Omnara.

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

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

yamlКопировать
# Пример конфигурации для включения SQL и документации
analysis_targets:
  - type: source_code
    path: "./src"
  - type: sql_schema
    path: "./database/schema.sql"
  - type: documentation
    path: "./docs/architecture.pdf"

graph_settings:
  include_relationships: true
  depth: 3 # Глубина связей для построения графа

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

Интеграция в рабочий процесс разработчика

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

С практической точки зрения, Graphify не заменяет IDE, а служит «картой местности» для ИИ-агентов, которые работают внутри них. Когда вы используете Claude Code или Cursor, основная проблема заключается в потере контекста при масштабировании проекта. Агент видит файлы, которые вы открыли, но он плохо понимает глубокие связи между, например, схемой базы данных и логикой бизнес-сервиса.

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

Для начала работы нужно экспортировать граф в формате, который агент сможет прочитать (обычно это JSON или упрощенный Markdown-список связей). Сначала сгенерируйте структуру проекта:

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

После этого вы можете передать этот файл агенту. В Claude Code это делается через явное указание файла при запросе:

bashКопировать
# Пример запроса к Claude Code с использованием графа
claude "Проанализируй связь между UserEntity и AuthService, используя graph.json"

Это дает предсказуемость: агент не будет гадать, как связаны компоненты, а обратится к структуре, которую Graphify построил на основе AST (Abstract Syntax Tree). Такой подход во многом перекликается с методами, которые описаны в статье про реверс-инжиниринг с помощью AI-агентов, где точность понимания структуры кода критически важна для успеха операции.

Настройка навыка для Gemini CLI

Если вы предпочитаете работать через интерфейс командной строки и используете Gemini CLI, Graphify можно интегрировать как «навык» (skill) или системный промпт, который подгружает контекст графа. Здесь мы не полагаемся на автоматическую индексацию IDE, а делаем это явно.

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

Для автоматизации процесса можно создать небольшой shell-скрипт, который будет обновлять контекст перед каждым важным запросом. Это обеспечит актуальность знаний агента о коде.

bashКопировать
#!/bin/bash
# Скрипт для подготовки контекста перед запуском Gemini CLI

echo "Обновление графа знаний..."
graphify analyze ./src --format markdown --output context_graph.md

echo "Запуск анализа..."
# Передаем файл графа как часть системного контекста
gemini-cli "Используй предоставленный контекст для ответа на вопрос: $1" --context context_graph.md

При использовании такого подхода важно помнить о оптимизации Git для работы AI-агентов. Если граф генерируется слишком часто и записывается в репозиторий, это может засорять историю коммитов. Я всегда добавляю context_graph.md в .gitignore, чтобы работать только с локальными временными файлами.

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

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

Когда графовый подход эффективнее RAG

Когда мы говорим об использовании LLM для работы с кодом, классический RAG (Retrieval-Augmented Generation) на основе векторного поиска часто подводит. Проблема в том, что векторный поиск ищет семантическую близость: он находит куски текста, которые «похожи» на запрос. Но программирование — это не про сходство слов, а про жесткие связи.

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

С практической точки зрения, преимущество графа проявляется в трёх аспектах:

1. Точность навигации. Вместо того чтобы гадать, какой кусок кода релевантен, мы идем по ребрам графа: Function Definition $\to$ Function Call $\to$ Module Import.
2. Отсутствие галлюцинаций в структуре. Векторный поиск может «притянуть» похожую по названию функцию из другого контекста. Граф же четко знает, что calculate_total() в модуле billing и calculate_total() в модуле shipping — это разные сущности.
3. Предсказуемость контекста. Мы можем ограничить область поиска не «похожими кусками», а конкретным поддеревом графа.

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

Сценарии использования для сложных репозиториев

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

1. Анализ влияния изменений (Impact Analysis)

Представьте, что вам нужно изменить сигнатуру метода в глубоко вложенном сервисе. Чтобы понять, что «сломается», недостаточно найти все упоминания этого метода. Нужно понять, какие высокоуровневые компоненты зависят от цепочки вызовов, которая в итоге приводит к этому методу.

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

2. Реверс-инжиниринг и онбординг

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

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

3. Проверка соответствия SQL-схем и кода

Частая проблема: в коде используется поле user_id, а в базе данных оно называется id_user. Graphify позволяет объединить схему БД и AST кода в единую структуру. Это позволяет выявлять несоответствия на этапе анализа, а не когда приложение упадет с ошибкой в рантайме.

Пример того, как может выглядеть конфигурация для индексации проекта (условно, через CLI инструмента):

bashКопировать
# Индексация репозитория с учетом SQL-схем и документации
graphify index ./src \
  --include-sql ./migrations \
  --include-docs ./docs \
  --output ./knowledge_graph.json

После построения графа, вы можете использовать его для обучения или контекстного наполнения агентов. Если вы планируете строить сложную систему управления, рекомендую посмотреть, как это реализовано в Omnara, где управление агентами требует чёткого понимания контекста.

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

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

Чем Graphify отличается от стандартных RAG-систем?

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

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

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

Какие языки программирования поддерживает Graphify?

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

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

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

Как точность графа зависит от качества исходного кода?

Точность графа напрямую зависит от возможности парсера построить корректное AST, поэтому код должен быть синтаксически верным. Если в проекте много неразмеченного или невалидного кода, инструмент не сможет выстроить полные связи. С практической точки зрения, чистота и структурированность кодовой базы — залог предсказуемости работы графа.