Proveedor de Contexto de Neo4j GraphRAG

El proveedor de contexto Neo4j GraphRAG añade capacidades de Generación Aumentada de Recuperación (RAG) a los agentes de Agent Framework utilizando un grafo de conocimiento Neo4j. Admite modos de búsqueda vectorial, de texto completo e híbrido, con recorridos de grafos opcionales para enriquecer los resultados con entidades relacionadas a través de consultas de Cypher personalizadas.

En escenarios de gráfico de conocimiento en los que las relaciones entre entidades son importantes, este proveedor recupera subgráficos pertinentes en lugar de fragmentos de texto aislados, lo que proporciona a los agentes un contexto más completo para generar respuestas.

¿Por qué usar Neo4j para GraphRAG?

• Recuperación mejorada del grafo: la búsqueda vectorial estándar devuelve fragmentos aislados; el recorrido del grafo sigue las conexiones a entidades relacionadas con la superficie, lo que proporciona a los agentes un contexto más completo.
• Modos de búsqueda flexibles: combine la similitud de vectores, la palabra clave/BM25 y el recorrido de grafos en una sola consulta.
• Consultas de recuperación personalizadas: las consultas de Cypher permiten controlar exactamente qué relaciones se deben recorrer y qué contexto devolver.

Nota:

Neo4j ofrece dos integraciones independientes para Agent Framework. Este proveedor es para GraphRAG: la búsqueda de un grafo de conocimiento existente para fundamentar las respuestas del agente. Para obtener memoria persistente que aprende de las conversaciones y crea un gráfico de conocimiento a lo largo del tiempo, consulte el proveedor de memoria Neo4j.

Prerrequisitos

• Una instancia neo4j (autohospedado o Neo4j AuraDB) con un índice de vector o texto completo configurado
• Un proyecto de Azure AI Foundry con un modelo de chat implementado y un modelo de inserción (por ejemplo, text-embedding-3-small)
• Conjunto de variables de entorno: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, , AZURE_AI_SERVICES_ENDPOINT, AZURE_AI_EMBEDDING_NAME
• Credenciales de la CLI de Azure configuradas (az login)
• .NET 8.0 o posterior

Instalación

dotnet add package Neo4j.AgentFramework.GraphRAG

Uso

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.OpenAI;
using Microsoft.Extensions.AI;
using Neo4j.AgentFramework.GraphRAG;
using Neo4j.Driver;

// Read connection details from environment variables
var neo4jSettings = new Neo4jSettings();
var azureEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_SERVICES_ENDPOINT")!;

// Create embedding generator
var credential = new DefaultAzureCredential();
var azureClient = new AzureOpenAIClient(new Uri(azureEndpoint), credential);

IEmbeddingGenerator<string, Embedding<float>> embedder = azureClient
    .GetEmbeddingClient("text-embedding-3-small")
    .AsIEmbeddingGenerator();

// Create Neo4j driver
await using var driver = GraphDatabase.Driver(
    neo4jSettings.Uri, AuthTokens.Basic(neo4jSettings.Username, neo4jSettings.Password!));

// Create the Neo4j context provider
await using var provider = new Neo4jContextProvider(driver, new Neo4jContextProviderOptions
{
    IndexName = "chunkEmbeddings",
    IndexType = IndexType.Vector,
    EmbeddingGenerator = embedder,
    TopK = 5,
    RetrievalQuery = """
        MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
        OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
        RETURN node.text AS text, score, doc.title AS title, company.name AS company
        ORDER BY score DESC
        """,
});

// Create an agent with the provider
AIAgent agent = azureClient
    .GetChatClient("gpt-4o")
    .AsIChatClient()
    .AsBuilder()
    .UseAIContextProviders(provider)
    .BuildAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new ChatOptions
        {
            Instructions = "You are a financial analyst assistant.",
        },
    });

var session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What risks does Acme Corp face?", session));

Características clave

• Impulsado por índices: funciona con cualquier índice vectorial o de texto completo de Neo4j
• Recorrido del grafo: consultas Cypher personalizadas enriquecen los resultados de búsqueda con entidades relacionadas
• Modos de búsqueda: Vector (similitud semántica), texto completo (palabra clave/BM25) o híbrido (ambos combinados)

Recursos

• Repositorio del proveedor de contexto neo4j
• Página del paquete NuGet
• Taller: Proveedores de Contexto Neo4j para el Framework de Agentes

Prerrequisitos

• Una instancia neo4j (autohospedado o Neo4j AuraDB) con un índice de vector o texto completo configurado
• Un proyecto de Azure AI Foundry con un modelo de chat implementado y un modelo de inserción (por ejemplo, text-embedding-ada-002)
• Conjunto de variables de entorno: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, FOUNDRY_PROJECT_ENDPOINT, , , FOUNDRY_MODELAZURE_AI_EMBEDDING_NAME
• Credenciales de la CLI de Azure configuradas (az login)
• Python 3.10 o posterior

Instalación

pip install agent-framework-neo4j

Uso

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings, AzureAISettings, AzureAIEmbedder
from azure.identity import DefaultAzureCredential
from azure.identity.aio import AzureCliCredential

# Reads NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD from environment variables
neo4j_settings = Neo4jSettings()

# Reads FOUNDRY_PROJECT_ENDPOINT, AZURE_AI_EMBEDDING_NAME from environment variables
azure_settings = AzureAISettings()

sync_credential = DefaultAzureCredential()
embedder = AzureAIEmbedder(
    endpoint=azure_settings.inference_endpoint,
    credential=sync_credential,
    model=azure_settings.embedding_model,
)

neo4j_provider = Neo4jContextProvider(
    uri=neo4j_settings.uri,
    username=neo4j_settings.username,
    password=neo4j_settings.get_password(),
    index_name=neo4j_settings.vector_index_name,
    index_type="vector",
    embedder=embedder,
    top_k=5,
    retrieval_query="""
        MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
        OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
        RETURN node.text AS text, score, doc.title AS title, company.name AS company
        ORDER BY score DESC
    """,
)

async with (
    neo4j_provider,
    AzureCliCredential() as credential,
    Agent(
        client=FoundryChatClient(
            credential=credential,
            project_endpoint=azure_settings.project_endpoint,
            model=os.environ["FOUNDRY_MODEL"],
        ),
        instructions="You are a financial analyst assistant.",
        context_providers=[neo4j_provider],
    ) as agent,
):
    session = agent.create_session()
    response = await agent.run("What risks does Acme Corp face?", session=session)

Características clave

• Impulsado por índices: funciona con cualquier índice vectorial o de texto completo de Neo4j
• Recorrido del grafo: consultas Cypher personalizadas enriquecen los resultados de búsqueda con entidades relacionadas
• Modos de búsqueda: Vector (similitud semántica), texto completo (palabra clave/BM25) o híbrido (ambos combinados)

Recursos

• Repositorio del proveedor de contexto neo4j
• Página del paquete pyPI
• Taller: Proveedores de Contexto Neo4j para el Framework de Agentes

Pasos siguientes

Proveedor de memoria Neo4j