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.
247 lines
8.4 KiB
Markdown
247 lines
8.4 KiB
Markdown
---
|
|
layout: default
|
|
title: "Proveniência de Extração: Modelo de Subgrafo"
|
|
parent: "Portuguese (Beta)"
|
|
---
|
|
|
|
# Proveniência de Extração: Modelo de Subgrafo
|
|
|
|
> **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.
|
|
|
|
## Problema
|
|
|
|
A proveniência em tempo de extração atualmente gera uma reificação completa para cada
|
|
<<<<<<< HEAD
|
|
tripla extraída: um `stmt_uri`, `activity_uri` e metadados PROV-O associados para cada
|
|
fato de conhecimento. O processamento de um bloco que gera 20 relacionamentos produz aproximadamente 220 triplas de proveniência, além de
|
|
aproximadamente 20 triplas de conhecimento — uma sobrecarga de aproximadamente 10:1.
|
|
|
|
|
|
Isso é caro (armazenamento, indexação, transmissão) e semanticamente
|
|
impreciso. Cada bloco é processado por uma única chamada de LLM que produz
|
|
todas as suas triplas em uma única transação. O modelo atual, baseado em tripla,
|
|
=======
|
|
tripla extraída: um `stmt_uri`, `activity_uri` e metadados PROV-O associados para
|
|
cada fato de conhecimento. O processamento de um bloco que gera 20 relacionamentos produz
|
|
aproximadamente 220 triplas de proveniência, além das aproximadamente 20 triplas de
|
|
conhecimento — uma sobrecarga de aproximadamente 10:1.
|
|
|
|
Isso é caro (armazenamento, indexação, transmissão) e semanticamente
|
|
impreciso. Cada bloco é processado por uma única chamada de LLM que produz
|
|
todas as suas triplas em uma única transação. O modelo atual, por tripla,
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|
obscure isso, criando a ilusão de 20 eventos de extração independentes.
|
|
|
|
|
|
Além disso, dois dos quatro processadores de extração (kg-extract-ontology,
|
|
<<<<<<< HEAD
|
|
kg-extract-agent) não possuem proveniência, deixando lacunas no registro de auditoria.
|
|
|
|
|
|
## Solução
|
|
|
|
Substituir a reificação por tripla por um **modelo de subgrafo**: um registro de proveniência
|
|
por extração de bloco, compartilhado entre todas as triplas produzidas a partir desse
|
|
bloco.
|
|
=======
|
|
kg-extract-agent) não possuem proveniência, deixando lacunas no registro de
|
|
auditoria.
|
|
|
|
## Solução
|
|
|
|
Substituir a reificação por tripla por um **modelo de subgrafo**: um registro de
|
|
proveniência por extração de bloco, compartilhado entre todas as triplas produzidas
|
|
a partir desse bloco.
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|
|
|
### Mudança de Terminologia
|
|
|
|
| Antigo | Novo |
|
|
|-----|-----|
|
|
| `stmt_uri` (`https://trustgraph.ai/stmt/{uuid}`) | `subgraph_uri` (`https://trustgraph.ai/subgraph/{uuid}`) |
|
|
| `statement_uri()` | `subgraph_uri()` |
|
|
| `tg:reifies` (1:1, identidade) | `tg:contains` (1:muitos, contenção) |
|
|
|
|
### Estrutura Alvo
|
|
|
|
Todas as triplas de proveniência devem ser inseridas no grafo nomeado `urn:graph:source`.
|
|
|
|
```
|
|
# Subgraph contains each extracted triple (RDF-star quoted triples)
|
|
<subgraph> tg:contains <<s1 p1 o1>> .
|
|
<subgraph> tg:contains <<s2 p2 o2>> .
|
|
<subgraph> tg:contains <<s3 p3 o3>> .
|
|
|
|
# Derivation from source chunk
|
|
<subgraph> prov:wasDerivedFrom <chunk_uri> .
|
|
<subgraph> prov:wasGeneratedBy <activity> .
|
|
|
|
# Activity: one per chunk extraction
|
|
<activity> rdf:type prov:Activity .
|
|
<activity> rdfs:label "{component_name} extraction" .
|
|
<activity> prov:used <chunk_uri> .
|
|
<activity> prov:wasAssociatedWith <agent> .
|
|
<activity> prov:startedAtTime "2026-03-13T10:00:00Z" .
|
|
<activity> tg:componentVersion "0.25.0" .
|
|
<activity> tg:llmModel "gpt-4" . # if available
|
|
<activity> tg:ontology <ontology_uri> . # if available
|
|
|
|
# Agent: stable per component
|
|
<agent> rdf:type prov:Agent .
|
|
<agent> rdfs:label "{component_name}" .
|
|
```
|
|
|
|
### Comparação de Volume
|
|
|
|
Para um conjunto de dados que produz N triplas extraídas:
|
|
|
|
| | Antigo (por tripla) | Novo (subgrafo) |
|
|
|---|---|---|
|
|
| `tg:contains` / `tg:reifies` | N | N |
|
|
| Triplas de atividade | ~9 x N | ~9 |
|
|
| Triplas de agente | 2 x N | 2 |
|
|
| Metadados de declaração/subgrafo | 2 x N | 2 |
|
|
| **Total de triplas de rastreabilidade** | **~13N** | **N + 13** |
|
|
| **Exemplo (N=20)** | **~260** | **33** |
|
|
|
|
## Escopo
|
|
|
|
### Processadores a serem Atualizados (rastreabilidade existente, por tripla)
|
|
|
|
**kg-extract-definitions**
|
|
(`trustgraph-flow/trustgraph/extract/kg/definitions/extract.py`)
|
|
|
|
Atualmente, chama `statement_uri()` + `triple_provenance_triples()` dentro
|
|
do loop por definição.
|
|
|
|
Alterações:
|
|
Mover a criação de `subgraph_uri()` e `activity_uri()` antes do loop
|
|
Coletar triplas `tg:contains` dentro do loop
|
|
Emitir bloco compartilhado de atividade/agente/derivação uma vez após o loop
|
|
|
|
**kg-extract-relationships**
|
|
(`trustgraph-flow/trustgraph/extract/kg/relationships/extract.py`)
|
|
|
|
Mesmo padrão que definições. As mesmas alterações.
|
|
|
|
### Processadores a serem Adicionados para Rastreabilidade (atualmente ausente)
|
|
|
|
**kg-extract-ontology**
|
|
(`trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`)
|
|
|
|
Atualmente, emite triplas sem rastreabilidade. Adicionar rastreabilidade de subgrafo
|
|
usando o mesmo padrão: um subgrafo por conjunto de dados, `tg:contains` para cada
|
|
tripla extraída.
|
|
|
|
**kg-extract-agent**
|
|
(`trustgraph-flow/trustgraph/extract/kg/agent/extract.py`)
|
|
|
|
Atualmente, emite triplas sem rastreabilidade. Adicionar rastreabilidade de subgrafo
|
|
usando o mesmo padrão.
|
|
|
|
### Alterações na Biblioteca Compartilhada de Rastreabilidade
|
|
|
|
**`trustgraph-base/trustgraph/provenance/triples.py`**
|
|
|
|
Substituir `triple_provenance_triples()` por `subgraph_provenance_triples()`
|
|
Nova função aceita uma lista de triplas extraídas em vez de uma única
|
|
Gera um `tg:contains` por tripla, bloco compartilhado de atividade/agente
|
|
Remover `triple_provenance_triples()` antigo
|
|
|
|
**`trustgraph-base/trustgraph/provenance/uris.py`**
|
|
|
|
Substituir `statement_uri()` por `subgraph_uri()`
|
|
|
|
**`trustgraph-base/trustgraph/provenance/namespaces.py`**
|
|
|
|
Substituir `TG_REIFIES` por `TG_CONTAINS`
|
|
|
|
<<<<<<< HEAD
|
|
### Não no Escopo
|
|
=======
|
|
### Não está no Escopo
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|
|
|
**kg-extract-topics**: processador de estilo antigo, não usado atualmente em
|
|
fluxos padrão
|
|
**kg-extract-rows**: produz linhas, não triplas, modelo de rastreabilidade
|
|
diferente
|
|
**Rastreabilidade em tempo de consulta** (`urn:graph:retrieval`): questão separada,
|
|
já usa um padrão diferente (pergunta/exploração/foco/síntese)
|
|
**Rastreabilidade de documento/página/conjunto de dados** (decodificador PDF, divisor): já usa
|
|
`derived_entity_triples()` que é por entidade, não por tripla — não há
|
|
problema de redundância
|
|
|
|
## Notas de Implementação
|
|
|
|
### Reestruturação do Loop do Processador
|
|
|
|
Antes (por tripla, em relacionamentos):
|
|
```python
|
|
for rel in rels:
|
|
# ... build relationship_triple ...
|
|
stmt_uri = statement_uri()
|
|
prov_triples = triple_provenance_triples(
|
|
stmt_uri=stmt_uri,
|
|
extracted_triple=relationship_triple,
|
|
...
|
|
)
|
|
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
|
```
|
|
|
|
Após (subgrafo):
|
|
```python
|
|
sg_uri = subgraph_uri()
|
|
|
|
for rel in rels:
|
|
# ... build relationship_triple ...
|
|
extracted_triples.append(relationship_triple)
|
|
|
|
prov_triples = subgraph_provenance_triples(
|
|
subgraph_uri=sg_uri,
|
|
extracted_triples=extracted_triples,
|
|
chunk_uri=chunk_uri,
|
|
component_name=default_ident,
|
|
component_version=COMPONENT_VERSION,
|
|
llm_model=llm_model,
|
|
ontology_uri=ontology_uri,
|
|
)
|
|
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
|
```
|
|
|
|
<<<<<<< HEAD
|
|
### Nova Assinatura de Auxílio
|
|
=======
|
|
### Nova Assinatura de Ajuda
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|
|
|
```python
|
|
def subgraph_provenance_triples(
|
|
subgraph_uri: str,
|
|
extracted_triples: List[Triple],
|
|
chunk_uri: str,
|
|
component_name: str,
|
|
component_version: str,
|
|
llm_model: Optional[str] = None,
|
|
ontology_uri: Optional[str] = None,
|
|
timestamp: Optional[str] = None,
|
|
) -> List[Triple]:
|
|
"""
|
|
Build provenance triples for a subgraph of extracted knowledge.
|
|
|
|
Creates:
|
|
- tg:contains link for each extracted triple (RDF-star quoted)
|
|
- One prov:wasDerivedFrom link to source chunk
|
|
- One activity with agent metadata
|
|
"""
|
|
```
|
|
|
|
### Mudança Significativa
|
|
|
|
<<<<<<< HEAD
|
|
Esta é uma mudança significativa no modelo de rastreabilidade. A rastreabilidade não
|
|
=======
|
|
Esta é uma mudança significativa no modelo de rastreabilidade. A rastreabilidade ainda não
|
|
>>>>>>> 82edf2d (New md files from RunPod)
|
|
foi lançada, portanto, nenhuma migração é necessária. O código antigo `tg:reifies` /
|
|
`statement_uri` pode ser removido completamente.
|