mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
8954fa3ad7
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
280 lines
14 KiB
Markdown
280 lines
14 KiB
Markdown
---
|
||
layout: default
|
||
title: "Объяснимость работы агента: Регистрация происхождения"
|
||
parent: "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.
|
||
|
||
## Обзор
|
||
|
||
Добавьте регистрацию происхождения в цикл работы агента React, чтобы сеансы работы агента можно было отслеживать и отлаживать с использованием той же инфраструктуры объяснимости, что и в GraphRAG.
|
||
|
||
**Принятые решения:**
|
||
Запись в `urn:graph:retrieval` (общий граф объяснимости)
|
||
Линейная цепочка зависимостей на данный момент (анализ N → был получен из → анализ N-1)
|
||
Инструменты являются непрозрачными "черными ящиками" (записывайте только входные и выходные данные)
|
||
Поддержка DAG отложена до будущей итерации
|
||
|
||
## Типы сущностей
|
||
|
||
И GraphRAG, и Agent используют PROV-O в качестве базовой онтологии с подтипами, специфичными для TrustGraph:
|
||
|
||
### Типы GraphRAG
|
||
| Сущность | Тип PROV-O | Типы TG | Описание |
|
||
|--------|-------------|----------|-------------|
|
||
| Вопрос | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Запрос пользователя |
|
||
| Исследование | `prov:Entity` | `tg:Exploration` | Ряды, извлеченные из графа знаний |
|
||
| Фокус | `prov:Entity` | `tg:Focus` | Выбранные ряды с обоснованием |
|
||
| Синтез | `prov:Entity` | `tg:Synthesis` | Окончательный ответ |
|
||
|
||
### Типы Agent
|
||
| Сущность | Тип PROV-O | Типы TG | Описание |
|
||
|--------|-------------|----------|-------------|
|
||
| Вопрос | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Запрос пользователя |
|
||
| Анализ | `prov:Entity` | `tg:Analysis` | Каждый цикл "думай/действуй/наблюдай" |
|
||
| Вывод | `prov:Entity` | `tg:Conclusion` | Окончательный ответ |
|
||
|
||
### Типы Document RAG
|
||
| Сущность | Тип PROV-O | Типы TG | Описание |
|
||
|--------|-------------|----------|-------------|
|
||
| Вопрос | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Запрос пользователя |
|
||
| Исследование | `prov:Entity` | `tg:Exploration` | Части, извлеченные из хранилища документов |
|
||
| Синтез | `prov:Entity` | `tg:Synthesis` | Окончательный ответ |
|
||
|
||
**Примечание:** Document RAG использует подмножество типов GraphRAG (нет этапа "Фокус", поскольку нет этапа выбора/обоснования ребер).
|
||
|
||
### Подтипы вопросов
|
||
|
||
Все сущности "Вопрос" имеют `tg:Question` в качестве базового типа, но имеют определенный подтип для идентификации механизма извлечения:
|
||
|
||
| Подтип | Шаблон URI | Механизм |
|
||
|---------|-------------|-----------|
|
||
| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG на основе графа знаний |
|
||
| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG на основе документов/частей |
|
||
| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | Агент ReAct |
|
||
|
||
Это позволяет запрашивать все вопросы через `tg:Question`, одновременно фильтруя по конкретному механизму с помощью подтипа.
|
||
|
||
## Модель происхождения
|
||
|
||
```
|
||
Question (urn:trustgraph:agent:{uuid})
|
||
│
|
||
│ tg:query = "User's question"
|
||
│ prov:startedAtTime = timestamp
|
||
│ rdf:type = prov:Activity, tg:Question
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
|
||
│
|
||
│ tg:thought = "I need to query the knowledge base..."
|
||
│ tg:action = "knowledge-query"
|
||
│ tg:arguments = {"question": "..."}
|
||
│ tg:observation = "Result from tool..."
|
||
│ rdf:type = prov:Entity, tg:Analysis
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
|
||
│ ...
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Conclusion (urn:trustgraph:agent:{uuid}/final)
|
||
│
|
||
│ tg:answer = "The final response..."
|
||
│ rdf:type = prov:Entity, tg:Conclusion
|
||
```
|
||
|
||
### Модель происхождения документов RAG
|
||
|
||
```
|
||
Question (urn:trustgraph:docrag:{uuid})
|
||
│
|
||
│ tg:query = "User's question"
|
||
│ prov:startedAtTime = timestamp
|
||
│ rdf:type = prov:Activity, tg:Question
|
||
│
|
||
↓ prov:wasGeneratedBy
|
||
│
|
||
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
|
||
│
|
||
│ tg:chunkCount = 5
|
||
│ tg:selectedChunk = "chunk-id-1"
|
||
│ tg:selectedChunk = "chunk-id-2"
|
||
│ ...
|
||
│ rdf:type = prov:Entity, tg:Exploration
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
|
||
│
|
||
│ tg:content = "The synthesized answer..."
|
||
│ rdf:type = prov:Entity, tg:Synthesis
|
||
```
|
||
|
||
## Необходимые изменения
|
||
|
||
### 1. Изменения схемы
|
||
|
||
**Файл:** `trustgraph-base/trustgraph/schema/services/agent.py`
|
||
|
||
Добавить поля `session_id` и `collection` в `AgentRequest`:
|
||
```python
|
||
@dataclass
|
||
class AgentRequest:
|
||
question: str = ""
|
||
state: str = ""
|
||
group: list[str] | None = None
|
||
history: list[AgentStep] = field(default_factory=list)
|
||
user: str = ""
|
||
collection: str = "default" # NEW: Collection for provenance traces
|
||
streaming: bool = False
|
||
session_id: str = "" # NEW: For provenance tracking across iterations
|
||
```
|
||
|
||
**Файл:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
|
||
|
||
Обновить переводчик для обработки `session_id` и `collection` как в `to_pulsar()`, так и в `from_pulsar()`.
|
||
|
||
### 2. Добавить компонент "Explainability Producer" в сервис Agent
|
||
|
||
**Файл:** `trustgraph-flow/trustgraph/agent/react/service.py`
|
||
|
||
Зарегистрировать компонент "explainability" (в соответствии с тем же шаблоном, что и GraphRAG):
|
||
```python
|
||
from ... base import ProducerSpec
|
||
from ... schema import Triples
|
||
|
||
# In __init__:
|
||
self.register_specification(
|
||
ProducerSpec(
|
||
name = "explainability",
|
||
schema = Triples,
|
||
)
|
||
)
|
||
```
|
||
|
||
### 3. Генерация триплетов происхождения
|
||
|
||
**Файл:** `trustgraph-base/trustgraph/provenance/agent.py`
|
||
|
||
Создайте вспомогательные функции (подобные `question_triples`, `exploration_triples` и т.д. в GraphRAG):
|
||
```python
|
||
def agent_session_triples(session_uri, query, timestamp):
|
||
"""Generate triples for agent Question."""
|
||
return [
|
||
Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
|
||
Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
|
||
Triple(s=session_uri, p=TG_QUERY, o=query),
|
||
Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
|
||
]
|
||
|
||
def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
|
||
"""Generate triples for one Analysis step."""
|
||
return [
|
||
Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
|
||
Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
|
||
Triple(s=iteration_uri, p=TG_ACTION, o=action),
|
||
Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
|
||
Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
|
||
Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||
]
|
||
|
||
def agent_final_triples(final_uri, parent_uri, answer):
|
||
"""Generate triples for Conclusion."""
|
||
return [
|
||
Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||
Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
|
||
Triple(s=final_uri, p=TG_ANSWER, o=answer),
|
||
Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||
]
|
||
```
|
||
|
||
### 4. Определения типов
|
||
|
||
**Файл:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
||
|
||
Добавить типы сущностей, обеспечивающих объяснимость, и предикаты агентов:
|
||
```python
|
||
# Explainability entity types (used by both GraphRAG and Agent)
|
||
TG_QUESTION = TG + "Question"
|
||
TG_EXPLORATION = TG + "Exploration"
|
||
TG_FOCUS = TG + "Focus"
|
||
TG_SYNTHESIS = TG + "Synthesis"
|
||
TG_ANALYSIS = TG + "Analysis"
|
||
TG_CONCLUSION = TG + "Conclusion"
|
||
|
||
# Agent predicates
|
||
TG_THOUGHT = TG + "thought"
|
||
TG_ACTION = TG + "action"
|
||
TG_ARGUMENTS = TG + "arguments"
|
||
TG_OBSERVATION = TG + "observation"
|
||
TG_ANSWER = TG + "answer"
|
||
```
|
||
|
||
## Измененные файлы
|
||
|
||
| Файл | Изменение |
|
||
|------|--------|
|
||
| `trustgraph-base/trustgraph/schema/services/agent.py` | Добавлены session_id и collection в AgentRequest |
|
||
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Обновлен переводчик для новых полей |
|
||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Добавлены типы сущностей, предикаты агента и предикаты Document RAG |
|
||
| `trustgraph-base/trustgraph/provenance/triples.py` | Добавлены типы TG для конструкторов троек GraphRAG, добавлены конструкторы троек Document RAG |
|
||
| `trustgraph-base/trustgraph/provenance/uris.py` | Добавлены генераторы URI для Document RAG |
|
||
| `trustgraph-base/trustgraph/provenance/__init__.py` | Экспортированы новые типы, предикаты и функции Document RAG |
|
||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Добавлены explain_id и explain_graph в DocumentRagResponse |
|
||
| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Обновлен DocumentRagResponseTranslator для полей, связанных с объяснением |
|
||
| `trustgraph-flow/trustgraph/agent/react/service.py` | Добавлена логика создания и записи информации о объяснении |
|
||
| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Добавлен колбэк для информации о объяснении и выводятся тройки, содержащие информацию о происхождении |
|
||
| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Добавлен генератор информации о объяснении и подключен колбэк |
|
||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Обработка типов трассировки агента |
|
||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Отображение сессий агента вместе с GraphRAG |
|
||
|
||
## Созданные файлы
|
||
|
||
| Файл | Назначение |
|
||
|------|---------|
|
||
| `trustgraph-base/trustgraph/provenance/agent.py` | Генераторы троек, специфичные для агента |
|
||
|
||
## Обновления CLI
|
||
|
||
**Обнаружение:** И GraphRAG, и вопросы агента имеют тип `tg:Question`. Отличаются следующим:
|
||
1. Шаблон URI: `urn:trustgraph:agent:` против `urn:trustgraph:question:`
|
||
2. Выводимые сущности: `tg:Analysis` (агент) против `tg:Exploration` (GraphRAG)
|
||
|
||
**`list_explain_traces.py`:**
|
||
Отображает столбец "Тип" (Агент против GraphRAG)
|
||
|
||
**`show_explain_trace.py`:**
|
||
Автоматически определяет тип трассировки
|
||
Отображение информации об агенте: Вопрос → Шаги анализа → Вывод
|
||
|
||
## Обратная совместимость
|
||
|
||
`session_id` по умолчанию равно `""` - старые запросы работают, но не будут содержать информацию о происхождении
|
||
`collection` по умолчанию равно `"default"` - разумная альтернатива
|
||
CLI корректно обрабатывает оба типа трассировки
|
||
|
||
## Проверка
|
||
|
||
```bash
|
||
# Run an agent query
|
||
tg-invoke-agent -q "What is the capital of France?"
|
||
|
||
# List traces (should show agent sessions with Type column)
|
||
tg-list-explain-traces -U trustgraph -C default
|
||
|
||
# Show agent trace
|
||
tg-show-explain-trace "urn:trustgraph:agent:xxx"
|
||
```
|
||
|
||
## Будущие задачи (не входят в этот PR)
|
||
|
||
Зависимости DAG (когда анализ N использует результаты нескольких предыдущих анализов)
|
||
Связь с конкретными инструментами (KnowledgeQuery → его трассировка GraphRAG)
|
||
Потоковая передача метаданных (отправлять по мере выполнения, а не пакетами в конце)
|