> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avaliação do GraphRAG

> Uma comparação de benchmark entre GraphRAG e RAG tradicional em perguntas de recuperação multi-hop.

Esta avaliação compara o GraphRAG com o RAG tradicional no mesmo corpus de benchmark e no mesmo conjunto de perguntas.
O objetivo foi medir se a recuperação sensível a grafos melhora a resposta a perguntas multi-hop.

## O que foi implementado

O sistema avaliado não utilizou apenas a recuperação de chunks plana.
Ele implementou o GraphRAG com as seguintes etapas:

1. Dividir os documentos fonte em chunks.
2. Extrair entidades e relacionamentos desses chunks.
3. Construir um grafo de conhecimento a partir das entidades e relacionamentos extraídos.
4. Executar a recuperação padrão para obter evidências iniciais para uma pergunta do usuário.
5. Expandir através dos links do grafo para coletar evidências conectadas.
6. Reordenar o conjunto final de evidências antes da geração da resposta.

Esse é o comportamento do GraphRAG que foi avaliado.

## Contra o que foi comparado

A comparação utilizou uma linha de base RAG tradicional com o mesmo corpus e o mesmo modelo de resposta.

A única diferença entre as duas execuções foi o modo de recuperação:

* **RAG Baseline**: apenas recuperação plana de chunks
* **GraphRAG**: expansão guiada por grafo mais reranqueamento sensível ao grafo

Isso é importante porque isola o efeito do próprio GraphRAG.

## Design do benchmark

O benchmark foi projetado para testar a recuperação multi-hop, e não apenas buscas simples em um único chunk.

Ele utilizou:

* três grafos de conhecimento alvo
* nove grafos distratores semanticamente similares
* 108 documentos factuais curtos
* 24 perguntas que exigiam a ligação de fatos entre múltiplos chunks

Esse design é importante.
Se cada resposta já aparece em um chunk óbvio, o GraphRAG não mostrará muito benefício em relação ao RAG padrão.

## Método de avaliação

Ambos os modos de recuperação foram executados sobre o mesmo corpus de benchmark e o mesmo conjunto de perguntas.
Ambos então utilizaram o mesmo modelo de geração de resposta e o mesmo prompt de resposta.

A avaliação registrou três métricas:

* **Correspondência exata**: se a resposta final correspondeu exatamente à resposta ouro
* **Token F1**: sobreposição de tokens entre a resposta final e a resposta ouro
* **Recall de evidência\@5**: quanto da evidência de suporte necessária apareceu nos 5 principais chunks recuperados

## Como a API foi utilizada

O fluxo da API avaliado foi simples.
A mesma store e os mesmos documentos foram usados tanto para a baseline quanto para o GraphRAG.
Apenas o modo de consulta foi alterado.

### 1. Criar uma store GraphRAG

<CodeGroup>
  ```bash CLI theme={null}
  mka1 search graphrag create-graph-RAG-store \
    --body '{
      "store_name": "benchmark_graphrag",
      "embedding_model": "meetkai:functionary-pt",
      "extraction_model": "meetkai:functionary-pt",
      "chunk_size": 800,
      "chunk_overlap": 120,
      "max_hops": 2
    }' \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: "Bearer <mka1-api-key>",
      serverUrl: "https://apigw.mka1.com"
  );

  var res = await sdk.Search.Graphrag.CreateGraphRAGStoreAsync(
      xApiKeyId: "<id>",
      xUserId: "<end-user-id>",
      xExchangeJwtExternalUserId: "<end-user-id>",
      body: new CreateGraphRAGStoreRequest()
      {
          StoreName = "benchmark_graphrag",
          EmbeddingModel = "meetkai:functionary-pt",
          ExtractionModel = "meetkai:functionary-pt",
          ChunkSize = 800,
          ChunkOverlap = 120,
          MaxHops = 2,
      }
  );
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  res = sdk.search.graphrag.create_graph_rag_store(
      store_name="benchmark_graphrag",
      embedding_model="meetkai:functionary-pt",
      extraction_model="meetkai:functionary-pt",
      chunk_size=800,
      chunk_overlap=120,
      max_hops=2,
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/search/graphrag/stores \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "store_name": "benchmark_graphrag",
      "embedding_model": "meetkai:functionary-pt",
      "extraction_model": "meetkai:functionary-pt",
      "chunk_size": 800,
      "chunk_overlap": 120,
      "max_hops": 2
    }'
  ```
</CodeGroup>

### 2. Ingerir documentos

<CodeGroup>
  ```bash CLI theme={null}
  mka1 search graphrag ingest-graph-RAG-documents \
    --store-name benchmark_graphrag \
    --body '{
      "documents": [
        {
          "document_id": "doc_contract_award",
          "text": "Rivera Logistics won the Northern Bridge Sensors contract.",
          "metadata": { "source": "benchmark" }
        },
        {
          "document_id": "doc_parent_company",
          "text": "Atlas Infrastructure Group owns Rivera Logistics.",
          "metadata": { "source": "benchmark" }
        }
      ]
    }'
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: "Bearer <mka1-api-key>",
      serverUrl: "https://apigw.mka1.com"
  );

  var res = await sdk.Search.Graphrag.IngestGraphRAGDocumentsAsync(
      new MeetKai.MKA1.Types.Requests.IngestGraphRAGDocumentsRequest
      {
          StoreName = "benchmark_graphrag",
          XApiKeyId = "<id>",
          XUserId = "<end-user-id>",
          XExchangeJwtExternalUserId = "<end-user-id>",
          Body = new IngestGraphRAGDocumentsRequest
          {
              Documents = new List<GraphRAGDocument>
              {
                  new GraphRAGDocument
                  {
                      DocumentId = "doc_contract_award",
                      Text = "Rivera Logistics won the Northern Bridge Sensors contract.",
                      Metadata = new Dictionary<string, object> { { "source", "benchmark" } },
                  },
                  new GraphRAGDocument
                  {
                      DocumentId = "doc_parent_company",
                      Text = "Atlas Infrastructure Group owns Rivera Logistics.",
                      Metadata = new Dictionary<string, object> { { "source", "benchmark" } },
                  },
              },
          },
      }
  );
  ```

  ```python Python SDK theme={null}
  res = sdk.search.graphrag.ingest_graph_rag_documents(
      store_name="benchmark_graphrag",
      documents=[
          {
              "document_id": "doc_contract_award",
              "text": "Rivera Logistics won the Northern Bridge Sensors contract.",
              "metadata": {"source": "benchmark"},
          },
          {
              "document_id": "doc_parent_company",
              "text": "Atlas Infrastructure Group owns Rivera Logistics.",
              "metadata": {"source": "benchmark"},
          },
      ],
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/search/graphrag/stores/benchmark_graphrag/documents \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "documents": [
        {
          "document_id": "doc_contract_award",
          "text": "Rivera Logistics won the Northern Bridge Sensors contract.",
          "metadata": {
            "source": "benchmark"
          }
        },
        {
          "document_id": "doc_parent_company",
          "text": "Atlas Infrastructure Group owns Rivera Logistics.",
          "metadata": {
            "source": "benchmark"
          }
        }
      ]
    }'
  ```
</CodeGroup>

### 3. Executar a consulta baseline RAG

<CodeGroup>
  ```bash CLI theme={null}
  mka1 search graphrag query-graph-RAG-store \
    --store-name benchmark_graphrag \
    --body '{
      "query": "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      "mode": "baseline",
      "limit": 5,
      "seed_k": 8
    }'
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: "Bearer <mka1-api-key>",
      serverUrl: "https://apigw.mka1.com"
  );

  var res = await sdk.Search.Graphrag.QueryGraphRAGStoreAsync(
      new MeetKai.MKA1.Types.Requests.QueryGraphRAGStoreRequest
      {
          StoreName = "benchmark_graphrag",
          XApiKeyId = "<id>",
          XUserId = "<end-user-id>",
          XExchangeJwtExternalUserId = "<end-user-id>",
          Body = new GraphRAGQueryRequest
          {
              Query = "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
              Mode = GraphRAGQueryRequestMode.Baseline,
              Limit = 5,
              SeedK = 8,
          },
      }
  );
  ```

  ```python Python SDK theme={null}
  res = sdk.search.graphrag.query_graph_rag_store(
      store_name="benchmark_graphrag",
      query="Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      mode="baseline",
      limit=5,
      seed_k=8,
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/search/graphrag/stores/benchmark_graphrag/query \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "query": "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      "mode": "baseline",
      "limit": 5,
      "seed_k": 8
    }'
  ```
</CodeGroup>

### 4. Executar a consulta GraphRAG

<CodeGroup>
  ```bash CLI theme={null}
  mka1 search graphrag query-graph-RAG-store \
    --store-name benchmark_graphrag \
    --body '{
      "query": "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      "mode": "graph",
      "limit": 5,
      "seed_k": 8
    }'
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: "Bearer <mka1-api-key>",
      serverUrl: "https://apigw.mka1.com"
  );

  var res = await sdk.Search.Graphrag.QueryGraphRAGStoreAsync(
      new MeetKai.MKA1.Types.Requests.QueryGraphRAGStoreRequest
      {
          StoreName = "benchmark_graphrag",
          XApiKeyId = "<id>",
          XUserId = "<end-user-id>",
          XExchangeJwtExternalUserId = "<end-user-id>",
          Body = new GraphRAGQueryRequest
          {
              Query = "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
              Mode = GraphRAGQueryRequestMode.Graph,
              Limit = 5,
              SeedK = 8,
          },
      }
  );
  ```

  ```python Python SDK theme={null}
  res = sdk.search.graphrag.query_graph_rag_store(
      store_name="benchmark_graphrag",
      query="Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      mode="graph",
      limit=5,
      seed_k=8,
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/search/graphrag/stores/benchmark_graphrag/query \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "query": "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?",
      "mode": "graph",
      "limit": 5,
      "seed_k": 8
    }'
  ```
</CodeGroup>

Essa última etapa é a comparação chave.
A consulta, o corpus e o modelo de resposta permaneceram os mesmos.
Apenas o `mode` foi alterado:

* `baseline` = recuperação plana tradicional
* `graph` = recuperação guiada por grafo e reranqueamento

## Resultados medidos

A execução ao vivo do benchmark produziu os seguintes resultados:

| Método       | Correspondência Exata | Token F1 | Recall de Evidência\@5 |
| ------------ | --------------------: | -------: | ---------------------: |
| RAG Baseline |                 25,0% |    27,1% |                  55,9% |
| GraphRAG     |                 62,5% |    62,5% |                  71,9% |

Melhoria:

* **Correspondência Exata**: `+37,5` pontos
* **Token F1**: `+35,4` pontos
* **Recall de Evidência\@5**: `+16,0` pontos

## Limite de aceitação

O benchmark utilizou os seguintes critérios de aprovação:

* melhoria de correspondência exata de pelo menos `+5,0` pontos
* melhoria de recall de evidência\@5 de pelo menos `+10,0` pontos

A implementação avaliada do GraphRAG passou em ambos os critérios.

## Exemplos representativos de resultados por pergunta

Exemplos onde o GraphRAG teve sucesso e o RAG baseline não:

* "Who is the chief financial officer of the company that owns the Northern Bridge Sensors contract winner?"
  * RAG Baseline: `unknown`
  * GraphRAG: `Javier Nanda`
* "Which company acquired the firm that prepared a risk report for Meridian Ports Authority?"
  * RAG Baseline: `unknown`
  * GraphRAG: `Atlas Infrastructure Group`
* "Which company owns the company that won the Delta Reach Sensors contract?"
  * RAG Baseline: `unknown`
  * GraphRAG: `Bluepeak Transit Group`

Estas são perguntas multi-hop.
Elas exigem a ligação de fatos entre entidades conectadas, em vez de recuperar apenas um chunk que corresponda diretamente.

## Por que o GraphRAG teve melhor desempenho

O RAG baseline recuperou chunks semanticamente similares, mas às vezes não conseguiu recuperar as evidências conectadas necessárias para completar a cadeia de raciocínio.

O GraphRAG melhorou o desempenho ao:

* identificar as entidades iniciais relevantes a partir da pergunta
* atravessar os relacionamentos do grafo para encontrar evidências ligadas
* reranquear o conjunto final de evidências com sinais do grafo além da similaridade semântica

É por isso que a melhoria aparece mais claramente em perguntas multi-hop.

## Resumo

Neste benchmark, o GraphRAG superou o RAG tradicional tanto na precisão da resposta final quanto na recuperação das evidências de suporte.
Os maiores ganhos apareceram em perguntas que exigiam a ligação de fatos entre múltiplas entidades conectadas.