346 lines
21 KiB
Markdown
346 lines
21 KiB
Markdown
# RAG
|
||
|
||
## Состояние as is
|
||
|
||
RAG сейчас используется как общее ядро индексации и retrieval по коду и документации.
|
||
Основной storage - `rag_session` и многослойный индекс в БД.
|
||
|
||
## Основные части
|
||
|
||
- `RagService` - фасад индексации и retrieval
|
||
- `DocsIndexingPipeline` - индексация документации
|
||
- `CodeIndexingPipeline` - индексация кода
|
||
- `RagRepository` - persistence и retrieval
|
||
- `IntentRouterV2` - планирование retrieval: слои, фильтры, ограничения
|
||
- `RuntimeRetrievalAdapter` - выполнение retrieval в runtime
|
||
|
||
## Индексация
|
||
|
||
Индексация идет по двум направлениям:
|
||
|
||
- `DOCS`
|
||
- `CODE`
|
||
|
||
На вход подается snapshot или changes.
|
||
Для каждого файла выбирается подходящий pipeline.
|
||
На выходе формируются документы по слоям и сохраняются в RAG-хранилище.
|
||
|
||
## Структура БД
|
||
|
||
Все слои сохраняются в общую таблицу `rag_chunks`.
|
||
|
||
### Общие поля по слоям
|
||
|
||
| Поле БД | Назначение |
|
||
|---|---|
|
||
| `rag_session_id` | идентификатор сессии индексации |
|
||
| `path` | путь исходного файла |
|
||
| `content` | основной текст записи для retrieval |
|
||
| `layer` | идентификатор слоя |
|
||
| `title` | короткий заголовок записи |
|
||
| `lang` | язык исходного содержимого, в основном для code-слоев |
|
||
| `repo_id` | идентификатор репозитория или проекта |
|
||
| `commit_sha` | версия кода или документов на момент индексации |
|
||
| `span_start`, `span_end` | диапазон строк в исходном файле, если он есть |
|
||
| `embedding` | векторное представление записи |
|
||
| `metadata_json` | структурированные атрибуты конкретного слоя |
|
||
|
||
### Поля со смыслом слоя
|
||
|
||
Смысл конкретного слоя хранится в `metadata_json`.
|
||
Именно эти атрибуты определяют, какой объект был извлечен и как его интерпретировать в retrieval.
|
||
Домены и поддомены должны храниться в `metadata_json` явно.
|
||
|
||
## Слои DOCS
|
||
|
||
### `D0_DOC_CHUNKS`
|
||
|
||
Задача:
|
||
Хранит текстовые фрагменты документации для retrieval по содержимому разделов.
|
||
|
||
Формирование:
|
||
Документ сначала разбирается на frontmatter и body, затем body режется на секции через markdown chunker.
|
||
Для каждой секции создается отдельная запись слоя.
|
||
Нарезка идет по разделам документа.
|
||
Только в fallback-сценарии, когда markdown-структура не найдена, используется нарезка по фиксированным текстовым чанкам.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
|
||
| `type` | тип документа из frontmatter | `frontmatter.type` |
|
||
| `module` | модуль документа | `frontmatter.module` |
|
||
| `domain` | домен документа | `frontmatter.domain` |
|
||
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
|
||
| `tags` | теги документа | `frontmatter.tags` |
|
||
| `section_path` | полный путь секции в иерархии заголовков | результат `MarkdownDocChunker` |
|
||
| `section_title` | заголовок текущей секции | результат `MarkdownDocChunker` |
|
||
| `order` | порядок секции внутри документа | результат `MarkdownDocChunker` |
|
||
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
| `artifact_type` | тип артефакта, здесь `DOCS` | константа builder |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsContentParser`, `MarkdownDocChunker`, `DocsDocumentBuilder`
|
||
|
||
### `D1_DOCUMENT_CATALOG`
|
||
|
||
Задача:
|
||
Хранит карточку документа как точку входа в документ и его краткое описание.
|
||
|
||
Формирование:
|
||
Источник данных - frontmatter `as is`, summary и doc kind, вычисленный классификатором документации.
|
||
В `metadata_json` копируются все `key-value` из frontmatter без нормализации и без fallback для frontmatter-атрибутов.
|
||
Дополнительно в `metadata_json` добавляются служебные поля `source_path`, `summary_text`, `doc_kind`.
|
||
Атрибут `document_id` добавляется только при наличии `frontmatter.id` (fallback до пути файла не применяется).
|
||
В `content` попадает summary документа, а не склейка всех частей документа в сплошной текст.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `*` frontmatter fields | все поля frontmatter в исходном виде | frontmatter документа |
|
||
| `document_id` | идентификатор документа, добавляется только если в frontmatter есть `id` | `frontmatter.id` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
| `summary_text` | краткое содержание документа | секция `# Summary` |
|
||
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsFrontmatterParser`, `DocsClassifier`, `DocsContentParser`, `DocsDocumentBuilder`
|
||
|
||
### `D2_FACT_INDEX`
|
||
|
||
Задача:
|
||
Хранит атомарные факты в форме `subject-predicate-object` для точного retrieval по утверждениям.
|
||
|
||
Формирование:
|
||
Факты извлекаются из frontmatter и секций документа, после чего каждая найденная тройка превращается в отдельную запись.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `fact_id` | идентификатор факта | вычисляется builder из содержимого факта и пути |
|
||
| `subject_id` | субъект факта | `DocsFactExtractor` |
|
||
| `predicate` | предикат или тип связи | `DocsFactExtractor` |
|
||
| `object` | значение или объект факта | `DocsFactExtractor` |
|
||
| `object_ref` | ссылка на объект, если она выделена отдельно | `DocsFactExtractor` |
|
||
| `anchor` | место в документе, откуда взят факт | `DocsFactExtractor` |
|
||
| `tags` | теги факта | `DocsFactExtractor` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsFactExtractor`, `DocsDocumentBuilder`
|
||
|
||
### `D3_ENTITY_CATALOG`
|
||
|
||
Задача:
|
||
Хранит сущности, найденные в документации, чтобы искать документы и связи вокруг конкретной сущности.
|
||
|
||
Формирование:
|
||
Сущности извлекаются из frontmatter документа, после чего каждая сущность сохраняется отдельной записью.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `entity_name` | имя сущности | `DocsEntityExtractor` |
|
||
| `document_id` | идентификатор документа, где найдена сущность | `frontmatter.id`, иначе путь файла |
|
||
| `document_type` | тип документа-источника | `frontmatter.type` |
|
||
| `module` | модуль документа | `frontmatter.module` |
|
||
| `domain` | домен документа | `frontmatter.domain` |
|
||
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
|
||
| `tags` | теги документа или сущности | `frontmatter.tags` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsEntityExtractor`, `DocsDocumentBuilder`
|
||
|
||
### `D4_WORKFLOW_INDEX`
|
||
|
||
Задача:
|
||
Хранит workflow и сценарии из документации для ответов про flow, шаги и жизненный цикл процесса.
|
||
|
||
Формирование:
|
||
Workflow извлекаются из detail sections документа и сохраняются как отдельные сценарии.
|
||
Извлечение идет из структуры `Details -> ## Сценарий`.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `workflow_id` | идентификатор сценария | вычисляется builder из названия, anchor и документа |
|
||
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
|
||
| `workflow_name` | название сценария | блок `Details -> ## Сценарий -> **Название**` |
|
||
| `preconditions` | предусловия сценария | блок `Details -> ## Сценарий -> **Предусловия**` |
|
||
| `trigger` | триггер или событие запуска | блок `Details -> ## Сценарий -> **Триггер**` |
|
||
| `main_flow` | основной сценарий | блок `Details -> ## Сценарий -> **Основной сценарий**` |
|
||
| `alternative_flow` | альтернативные ветки | блок `Details -> ## Сценарий -> **Альтернативный сценарий**` |
|
||
| `error_handling` | обработка ошибок | блок `Details -> ## Сценарий -> **Обработка ошибок**` |
|
||
| `postconditions` | постусловия | блок `Details -> ## Сценарий -> **Постусловие**` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsWorkflowExtractor`, `DocsDocumentBuilder`
|
||
|
||
### `D5_RELATION_GRAPH`
|
||
|
||
Задача:
|
||
Хранит связи между документами и сущностями документации для navigation и related docs retrieval.
|
||
|
||
Формирование:
|
||
Связи извлекаются из frontmatter и сохраняются как отдельные relation edges.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `relation_id` | идентификатор связи | вычисляется builder из source, target, relation type и anchor |
|
||
| `source_id` | источник связи | `frontmatter.id` или source документа в extractor |
|
||
| `relation_type` | тип связи | `DocsRelationExtractor` |
|
||
| `target_id` | целевой объект связи | `DocsRelationExtractor` |
|
||
| `anchor` | место в документе, где обнаружена связь | `DocsRelationExtractor` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsRelationExtractor`, `DocsDocumentBuilder`
|
||
|
||
### `D6_INTEGRATION_INDEX`
|
||
|
||
Задача:
|
||
Хранит прикладные интеграции компонента, API, UI, сущности или внешней системы.
|
||
Используется для ответов на вопросы вида "какие интеграции есть у компонента".
|
||
|
||
Формирование:
|
||
Интеграции извлекаются из блока `## Integrations` документа.
|
||
Одна интеграция должна превращаться в отдельную запись слоя.
|
||
Описание интеграции может быть развернутым, а структурированные атрибуты должны выделяться в словарь.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `integration_id` | идентификатор интеграции | вычисляется builder из source, target и anchor |
|
||
| `source_id` | идентификатор объекта, для которого описана интеграция | `frontmatter.id` документа-источника |
|
||
| `source_type` | тип исходного объекта | `frontmatter.doc_type` |
|
||
| `target` | целевой объект интеграции | блок `## Integrations` |
|
||
| `target_type` | тип целевого объекта, например `api`, `ui`, `entity`, `service`, `external_system` | блок `## Integrations` |
|
||
| `direction` | направление интеграции | блок `## Integrations` |
|
||
| `interaction` | тип взаимодействия | блок `## Integrations` |
|
||
| `via` | технический канал интеграции | блок `## Integrations` |
|
||
| `purpose` | назначение интеграции | блок `## Integrations` |
|
||
| `details` | дополнительные атрибуты интеграции в виде словаря | блок `## Integrations` |
|
||
| `domain` | домен документа | `frontmatter.domain` |
|
||
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
|
||
| `source_path` | исходный путь документа | путь файла |
|
||
| `anchor` | место в документе, где описана интеграция | блок `## Integrations` |
|
||
|
||
Связанные классы:
|
||
`DocsIndexingPipeline`, `DocsIntegrationExtractor`, `DocsDocumentBuilder`
|
||
|
||
## Слои CODE
|
||
|
||
### `C0_SOURCE_CHUNKS`
|
||
|
||
Задача:
|
||
Хранит фрагменты исходного кода как базовый слой для цитирования, explain и точечной догрузки кода.
|
||
|
||
Формирование:
|
||
Исходный файл режется на кодовые чанки, и для каждого чанка создается отдельная запись.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `chunk_index` | порядковый номер чанка в файле | индекс чанка при нарезке |
|
||
| `chunk_type` | тип чанка, например функция, класс или текстовый блок | `CodeTextChunker` |
|
||
| `module_or_unit` | модуль, к которому относится chunk | вычисляется из пути файла |
|
||
| `is_test` | признак тестового файла | `is_test_path(path)` |
|
||
|
||
Связанные классы:
|
||
`CodeIndexingPipeline`, `CodeTextChunker`, `CodeTextDocumentBuilder`
|
||
|
||
### `C1_SYMBOL_CATALOG`
|
||
|
||
Задача:
|
||
Хранит символы кода: классы, функции и методы. Используется для поиска по именам и структуре кода.
|
||
|
||
Формирование:
|
||
Символы извлекаются `SymbolExtractor`, и каждый символ сохраняется как отдельная запись.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `symbol_id` | идентификатор символа | `SymbolExtractor` |
|
||
| `qname` | полное квалифицированное имя | `SymbolExtractor` |
|
||
| `kind` | тип символа: класс, функция, метод | `SymbolExtractor` |
|
||
| `signature` | сигнатура символа | `SymbolExtractor` |
|
||
| `parent_symbol_id` | родительский символ | `SymbolExtractor` |
|
||
| `package_or_module` | модуль или пакет символа | вычисляется из пути файла |
|
||
| `is_test` | признак тестового файла | `is_test_path(path)` |
|
||
|
||
Связанные классы:
|
||
`CodeIndexingPipeline`, `PythonAstParser`, `SymbolExtractor`, `SymbolDocumentBuilder`
|
||
|
||
### `C2_DEPENDENCY_GRAPH`
|
||
|
||
Задача:
|
||
Хранит связи между символами кода: вызовы, импорты, наследование. Используется для анализа зависимостей и flow.
|
||
|
||
Формирование:
|
||
Связи строятся `EdgeExtractor` по AST и списку символов, после чего каждая связь сохраняется отдельной записью.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `edge_id` | идентификатор связи | `EdgeExtractor` |
|
||
| `edge_type` | тип связи: вызов, импорт, наследование | `EdgeExtractor` |
|
||
| `src_symbol_id` | исходный символ | `EdgeExtractor` |
|
||
| `src_qname` | полное имя исходного символа | `EdgeExtractor` |
|
||
| `dst_symbol_id` | целевой символ, если он разрешен | `EdgeExtractor` |
|
||
| `dst_ref` | текстовая ссылка на целевой символ | `EdgeExtractor` |
|
||
| `resolution` | статус разрешения связи | `EdgeExtractor` |
|
||
| `is_test` | признак тестового файла | `is_test_path(path)` |
|
||
|
||
Связанные классы:
|
||
`CodeIndexingPipeline`, `EdgeExtractor`, `EdgeDocumentBuilder`
|
||
|
||
### `C3_ENTRYPOINTS`
|
||
|
||
Задача:
|
||
Хранит точки входа приложения: HTTP routes, CLI commands и другие entrypoints.
|
||
|
||
Формирование:
|
||
Детекторы ищут HTTP и CLI точки входа по символам файла, после чего каждый найденный entrypoint сохраняется отдельной записью.
|
||
|
||
Фиксация в БД:
|
||
| Атрибут в `metadata_json` | Описание | Источник |
|
||
|---|---|---|
|
||
| `entry_id` | идентификатор точки входа | detector entrypoint model |
|
||
| `entry_type` | тип точки входа | detector entrypoint model |
|
||
| `framework` | framework, в котором найдена точка входа | detector entrypoint model |
|
||
| `route_or_command` | route или команда | detector entrypoint model |
|
||
| `handler_symbol_id` | идентификатор обработчика | detector entrypoint model |
|
||
| `handler_symbol` | имя обработчика | detector entrypoint model |
|
||
| `declaring_symbol` | символ, в котором объявлен entrypoint | detector entrypoint model |
|
||
| `entrypoint_kind` | вид точки входа | detector entrypoint model |
|
||
| `http_method` | HTTP-метод | detector entrypoint model |
|
||
| `route_path` | путь маршрута | detector entrypoint model |
|
||
| `decorator_text` | текст декоратора или объявления | detector entrypoint model |
|
||
| `summary_text` | краткое описание точки входа | detector entrypoint model |
|
||
| `is_test` | признак тестового файла | `is_test_path(path)` |
|
||
| `lang_payload` | дополнительные данные детектора | detector metadata |
|
||
| `artifact_type` | тип артефакта, здесь `CODE` | константа builder |
|
||
|
||
Связанные классы:
|
||
`CodeIndexingPipeline`, `EntrypointDetectorRegistry`, `FastApiEntrypointDetector`, `FlaskEntrypointDetector`, `TyperClickEntrypointDetector`, `EntrypointDocumentBuilder`
|
||
|
||
### `C4_SEMANTIC_ROLES`
|
||
|
||
Задача:
|
||
Слой объявлен в enum и retrieval-планах как слой семантических ролей кода.
|
||
|
||
Формирование:
|
||
Слой формируется на основе символов, связей, dataflow slices и execution traces.
|
||
В текущем runtime этот слой не используется как активный маршрут, так как домен `CODE` отключен.
|
||
|
||
Фиксация в БД:
|
||
Смысловые атрибуты слоя сохраняются в `rag_chunks.metadata_json`.
|
||
Точное краткое описание состава этих атрибутов в текущем документе пока не зафиксировано.
|
||
|
||
Связанные классы:
|
||
`CodeIndexingPipeline`, `SemanticRoleBuilder`, `SemanticRoleDocumentBuilder`
|