trustgraph/docs/tech-specs/query-time-explainability.ru.md

layout	title	parent
default	Объяснимость во время выполнения запроса	Russian (Beta)

Объяснимость во время выполнения запроса

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Статус

Реализовано

Обзор

Эта спецификация описывает, как GraphRAG записывает и передает данные об объяснимости во время выполнения запроса. Цель - полная отслеживаемость: от окончательного ответа до выбранных ребер и исходных документов.

Объяснимость во время выполнения запроса фиксирует действия, которые выполняет конвейер GraphRAG во время рассуждений. Она связана с информацией о происхождении, которая записывается во время извлечения и фиксирует, откуда взялись факты графа знаний.

Терминология

Термин	Определение
Объяснимость	Запись о том, как был получен результат
Сессия	Одиночное выполнение запроса GraphRAG
Выбор ребра	Выбор релевантных ребер с использованием LLM и обоснованием
Цепь происхождения	Путь от ребра → фрагмента → страницы → документа

Архитектура

Поток объяснимости

GraphRAG Query
    │
    ├─► Session Activity
    │       └─► Query text, timestamp
    │
    ├─► Retrieval Entity
    │       └─► All edges retrieved from subgraph
    │
    ├─► Selection Entity
    │       └─► Selected edges with LLM reasoning
    │           └─► Each edge links to extraction provenance
    │
    └─► Answer Entity
            └─► Reference to synthesized response (in librarian)

Двухэтапная конвейерная обработка GraphRAG

1. Выбор ребер: LLM выбирает релевантные ребра из подграфа, предоставляя обоснование для каждого.
2. Синтез: LLM генерирует ответ, используя только выбранные ребра.

Такое разделение обеспечивает объяснимость - мы точно знаем, какие ребра внесли вклад.

Хранилище

Тройки, обеспечивающие объяснимость, хранятся в настраиваемой коллекции (по умолчанию: explainability). Используется онтология PROV-O для отношений происхождения. RDF-star для ссылок на ребра. Содержимое ответа хранится в сервисе librarian (не встроено - слишком большой объем).

Потоковая передача в реальном времени

События, обеспечивающие объяснимость, передаются клиенту в процессе выполнения запроса:

1. Создание сессии → событие отправлено.
2. Получение ребер → событие отправлено.
3. Выбор ребер с обоснованием → событие отправлено.
4. Синтез ответа → событие отправлено.

Клиент получает explain_id и explain_collection для получения полной информации.

Структура URI

Все URI используют пространство имен urn:trustgraph: с UUID:

Сущность	Шаблон URI
Сессия	urn:trustgraph:session:{uuid}
Получение	urn:trustgraph:prov:retrieval:{uuid}
Выбор	urn:trustgraph:prov:selection:{uuid}
Ответ	urn:trustgraph:prov:answer:{uuid}
Выбор ребра	urn:trustgraph:prov:edge:{uuid}:{index}

Модель RDF (PROV-O)

Сессия активности

<session-uri> a prov:Activity ;
    rdfs:label "GraphRAG query session" ;
    prov:startedAtTime "2024-01-15T10:30:00Z" ;
    tg:query "What was the War on Terror?" .

Получение сущности

<retrieval-uri> a prov:Entity ;
    rdfs:label "Retrieved edges" ;
    prov:wasGeneratedBy <session-uri> ;
    tg:edgeCount 50 .

Выбор сущности

<selection-uri> a prov:Entity ;
    rdfs:label "Selected edges" ;
    prov:wasDerivedFrom <retrieval-uri> ;
    tg:selectedEdge <edge-sel-0> ;
    tg:selectedEdge <edge-sel-1> .

<edge-sel-0> tg:edge << <s> <p> <o> >> ;
    tg:reasoning "This edge establishes the key relationship..." .

Ответная сущность

<answer-uri> a prov:Entity ;
    rdfs:label "GraphRAG answer" ;
    prov:wasDerivedFrom <selection-uri> ;
    tg:document <urn:trustgraph:answer:{uuid}> .

tg:document ссылается на ответ, хранящийся в сервисе librarian.

Константы пространства имен

Определены в trustgraph-base/trustgraph/provenance/namespaces.py:

Константа	URI
TG_QUERY	https://trustgraph.ai/ns/query
TG_EDGE_COUNT	https://trustgraph.ai/ns/edgeCount
TG_SELECTED_EDGE	https://trustgraph.ai/ns/selectedEdge
TG_EDGE	https://trustgraph.ai/ns/edge
TG_REASONING	https://trustgraph.ai/ns/reasoning
TG_CONTENT	https://trustgraph.ai/ns/content
TG_DOCUMENT	https://trustgraph.ai/ns/document

Схема GraphRagResponse

@dataclass
class GraphRagResponse:
    error: Error | None = None
    response: str = ""
    end_of_stream: bool = False
    explain_id: str | None = None
    explain_collection: str | None = None
    message_type: str = ""  # "chunk" or "explain"
    end_of_session: bool = False

Типы сообщений

message_type	Назначение
chunk	Текстовый ответ (потоковый или окончательный)
explain	Событие, связанное с объяснимостью, с ссылкой IRI

Жизненный цикл сессии

1. Несколько сообщений explain (сессия, получение, выбор, ответ)
2. Несколько сообщений chunk (потоковый ответ)
3. Окончательное сообщение chunk с end_of_session=True

Формат выбора ребер

LLM возвращает JSONL с выбранными ребрами:

{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}

id является хешем (labeled_s, labeled_p, labeled_o), вычисленным с помощью edge_id().

Сохранение URI

Проблема

GraphRAG отображает для LLM удобочитаемые метки, но для отслеживания происхождения необходимы исходные URI.

Решение

get_labelgraph() возвращает следующее: labeled_edges: Список (label_s, label_p, label_o) для LLM uri_map: Словарь, сопоставляющий edge_id(labels) → (uri_s, uri_p, uri_o)

При хранении данных для объяснения используются URI из uri_map.

Отслеживание происхождения

От узла к источнику

Выбранные узлы можно проследить до исходных документов:

1. Запрос для получения содержащего подграфа: ?subgraph tg:contains <<s p o>>
2. Переход по цепочке prov:wasDerivedFrom к корневому документу
3. Каждый шаг в цепочке: фрагмент → страница → документ

Поддержка тройных наборов в Cassandra

Сервис запросов Cassandra поддерживает сопоставление тройных наборов:

# In get_term_value():
elif term.type == TRIPLE:
    return serialize_triple(term.triple)

Это позволяет выполнять запросы, такие как:

?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>

Использование интерфейса командной строки

tg-invoke-graph-rag --explainable -q "What was the War on Terror?"

Формат вывода

[session] urn:trustgraph:session:abc123

[retrieval] urn:trustgraph:prov:retrieval:abc123

[selection] urn:trustgraph:prov:selection:abc123
    Selected 12 edge(s)
      Edge: (Guantanamo, definition, A detention facility...)
        Reason: Directly connects Guantanamo to the War on Terror
        Source: Chunk 1 → Page 2 → Beyond the Vigilant State

[answer] urn:trustgraph:prov:answer:abc123

Based on the provided knowledge statements...

Особенности

События объяснения в реальном времени во время запроса. Разрешение меток для компонентов ребер с помощью rdfs:label. Отслеживание цепочки источников с помощью prov:wasDerivedFrom. Кэширование меток для предотвращения повторных запросов.

Реализованные файлы

Файл	Назначение
trustgraph-base/trustgraph/provenance/uris.py	Генераторы URI
trustgraph-base/trustgraph/provenance/namespaces.py	Константы пространства имен RDF
trustgraph-base/trustgraph/provenance/triples.py	Конструкторы троек
trustgraph-base/trustgraph/schema/services/retrieval.py	Схема GraphRagResponse
trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py	Основной GraphRAG с сохранением URI
trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py	Сервис с интеграцией с библиотекарем
trustgraph-flow/trustgraph/query/triples/cassandra/service.py	Поддержка запросов троек в кавычках
trustgraph-cli/trustgraph/cli/invoke_graph_rag.py	CLI с отображением объяснений

Ссылки

PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/ RDF-star: https://w3c.github.io/rdf-star/ Происхождение во время извлечения: docs/tech-specs/extraction-time-provenance.md