Développer un agent de pipeline de requêtes LlamaIndex

Cette page vous explique comment développer un agent à l'aide du modèle LlamaIndex Query Pipelines (la classe LlamaIndexQueryPipelineAgent du SDK Vertex AI pour Python). Cet agent est conçu pour répondre à des questions à l'aide de la génération augmentée de récupération (RAG), comme la requête suivante : "Quelle est la vie de Paul Graham à l'université ?"

Procédez comme suit pour développer un agent à l'aide de LlamaIndex Query Pipelines :

Définir et configurer un modèle
Définir et utiliser un récupérateur
Définir et utiliser un synthétiseur de réponses
(Facultatif) Personnaliser le modèle de prompt
(Facultatif) Personnaliser l'orchestration

Avant de commencer

Assurez-vous que votre environnement est configuré en suivant la procédure décrite dans Configurer votre environnement.

Définir et configurer un modèle

Définissez et configurez un modèle à utiliser par votre agent LlamaIndex Query Pipeline.

Définissez la version du modèle :
```
model = "gemini-2.0-flash"
```

(Facultatif) Spécifiez les paramètres du modèle :

model_kwargs = {
    # vertexai_config (dict): By providing the region and project_id parameters,
    # you can enable model usage through Vertex AI.
    "vertexai_config": {
        "project": "PROJECT_ID",
        "location": "LOCATION"
    },
    # temperature (float): The sampling temperature controls the degree of
    # randomness in token selection.
    "temperature": 0.28,
    # context_window (int): The context window of the model.
    # If not provided, the default context window is 200000.
    "context_window": 200000,
    # max_tokens (int): Token limit determines the maximum
    # amount of text output from one prompt. If not provided,
    # the default max_tokens is 256.
    "max_tokens": 256,
}

Créez un LlamaIndexQueryPipelineAgent à l'aide des configurations de modèle suivantes :

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model=model,                # Required.
    model_kwargs=model_kwargs,  # Optional.
)

Si vous utilisez un environnement interactif (tel que le terminal ou le notebook Colab), vous pouvez interroger l'agent :

response = agent.query(input="What is Paul Graham's life in college?")

print(response)

Vous devriez obtenir un résultat semblable à celui-ci :

{'message': {'role': 'assistant',
  'additional_kwargs': {},
  'blocks': [{'block_type': 'text',
    'text': "Unfortunately, there's not a lot of publicly available information about Paul Graham's personal life in college. ..."}]},
  'raw': {'content': {'parts': [{'video_metadata': None,
      'thought': None,
      'code_execution_result': None,
      'executable_code': None,
      'file_data': None,
      'function_call': None,
      'function_response': None,
      'inline_data': None,
      'text': "Unfortunately, there's not a lot of publicly available information about Paul Graham's personal life in college. ..."}],
    'role': 'model'},
    'citation_metadata': None,
    'finish_message': None,
    'token_count': None,
    'avg_logprobs': -0.1468650027438327,
    'finish_reason': 'STOP',
    'grounding_metadata': None,
    'index': None,
    'logprobs_result': None,
    'safety_ratings': [{'blocked': None,
      'category': 'HARM_CATEGORY_HATE_SPEECH',
      'probability': 'NEGLIGIBLE',
      'probability_score': 0.022949219,
      'severity': 'HARM_SEVERITY_NEGLIGIBLE',
      'severity_score': 0.014038086},
    {'blocked': None,
      'category': 'HARM_CATEGORY_DANGEROUS_CONTENT',
      'probability': 'NEGLIGIBLE',
      'probability_score': 0.056640625,
      'severity': 'HARM_SEVERITY_NEGLIGIBLE',
      'severity_score': 0.029296875},
    {'blocked': None,
      'category': 'HARM_CATEGORY_HARASSMENT',
      'probability': 'NEGLIGIBLE',
      'probability_score': 0.071777344,
      'severity': 'HARM_SEVERITY_NEGLIGIBLE',
      'severity_score': 0.024047852},
    {'blocked': None,
      'category': 'HARM_CATEGORY_SEXUALLY_EXPLICIT',
      'probability': 'NEGLIGIBLE',
      'probability_score': 0.103515625,
      'severity': 'HARM_SEVERITY_NEGLIGIBLE',
      'severity_score': 0.05102539}],
    'usage_metadata': {'cached_content_token_count': None,
    'candidates_token_count': 222,
    'prompt_token_count': 10,
    'total_token_count': 232}},
  'delta': None,
  'logprobs': None,
  'additional_kwargs': {}}

(Facultatif) Personnaliser votre modèle

Le modèle LlamaIndexQueryPipelineAgent utilise Google GenAI par défaut pour fournir un accès à tous les modèles de base disponibles dans Google Cloud. Pour utiliser un modèle qui n'est pas disponible via Google GenAI, définissez model_builder= comme suit :

from typing import Optional

def model_builder(
    *,
    model_name: str,                      # Required. The name of the model
    model_kwargs: Optional[dict] = None,  # Optional. The model keyword arguments.
    **kwargs,                             # Optional. The remaining keyword arguments to be ignored.
):

Pour obtenir la liste des modèles de chat compatibles avec LlamaIndexQueryPipeline et de leurs fonctionnalités, consultez Intégrations LLM disponibles. Chaque modèle de chat utilise son propre ensemble de valeurs compatibles pour model= et model_kwargs=.

Google GenAI

Google GenAI est installé par défaut lorsque vous configurez votre environnement et est automatiquement utilisé dans LlamaIndexQueryPipelineAgent lorsque vous omettez model_builder.

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model=model,                # Required.
    model_kwargs=model_kwargs,  # Optional.
)

Anthropic

Suivez la documentation Anthropic pour configurer un compte et installer le package llama-index-llms-anthropic.

Définissez model_builder pour renvoyer le modèle Anthropic :

def model_builder(*, model_name: str, model_kwargs = None, **kwargs):
    from llama_index.llms.anthropic import Anthropic

    return Anthropic(model=model_name, **model_kwargs)

Utilisez le modèle Anthropic dans LlamaIndexQueryPipelineAgent :

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model="claude-3-opus-20240229",           # Required.
    model_builder=model_builder,              # Required.
    model_kwargs={
        "api_key": "ANTHROPIC_API_KEY",    # Required.
        "temperature": 0.28,                  # Optional.
    },
)

OpenAILike

Vous pouvez utiliser OpenAILike avec l'API ChatCompletions de Gemini.

Suivez la OpenAILike documentation pour installer le package :
```
pip install llama-index-llms-openai-like
```

Définissez un model_builder qui renvoie le modèle OpenAILike :

def model_builder(
    *,
    model_name: str,
    model_kwargs = None,
    project: str,   # Specified via vertexai.init
    location: str,  # Specified via vertexai.init
    **kwargs,
):
    import google.auth
    from llama_index.llms.openai_like import OpenAILike

    # Note: the credential lives for 1 hour by default.
    # After expiration, it must be refreshed.
    creds, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
    auth_req = google.auth.transport.requests.Request()
    creds.refresh(auth_req)

    if model_kwargs is None:
        model_kwargs = {}

    endpoint = f"https://{location}-aiplatform.googleapis.com"
    api_base = f'{endpoint}/v1beta1/projects/{project}/locations/{location}/endpoints/openapi'

    return OpenAILike(
        model=model_name,
        api_base=api_base,
        api_key=creds.token,
        **model_kwargs,
    )

Utilisez le modèle dans LlamaIndexQueryPipelineAgent :

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model="google/gemini-2.0-flash",  # Or "meta/llama3-405b-instruct-maas"
    model_builder=model_builder,        # Required.
    model_kwargs={
        "temperature": 0,               # Optional.
        "max_retries": 2,               # Optional.
    },
)

Définir et utiliser un récupérateur

Après avoir défini votre modèle, définissez le récupérateur qu'il utilise pour le raisonnement. Un récupérateur peut être créé en plus des index, mais il peut également être défini de manière exhaustive. Vous devez tester votre récupérateur localement.

Définissez un récupérateur qui renvoie les documents pertinents et les scores de similarité :

def retriever_builder(model, retriever_kwargs=None):
    import os
    import requests
    from llama_index.core import (
        StorageContext,
        VectorStoreIndex,
        load_index_from_storage,
    )
    from llama_index.core import SimpleDirectoryReader
    from llama_index.embeddings.vertex import VertexTextEmbedding
    import google.auth

    credentials, _ = google.auth.default()
    embed_model = VertexTextEmbedding(
        model_name="text-embedding-005", project="PROJECT_ID", credentials=credentials
    )

    data_dir = "data/paul_graham"
    essay_file = os.path.join(data_dir, "paul_graham_essay.txt")
    storage_dir = "storage"

    # --- Simple Download (if needed) ---
    if not os.path.exists(essay_file):
        os.makedirs(data_dir, exist_ok=True)  # Make sure the directory exists
        essay_url = "https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt"
        try:
            response = requests.get(essay_url)
            response.raise_for_status()  # Check for download errors
            with open(essay_file, "wb") as f:
                f.write(response.content)
            print("Essay downloaded.")
        except requests.exceptions.RequestException as e:
            print(f"Download failed: {e}")

    # --- Build/Load Index ---
    if not os.path.exists(storage_dir):
        print("Creating new index...")
        # --- Load Data ---
        reader = SimpleDirectoryReader(data_dir)
        docs = reader.load_data()

        index = VectorStoreIndex.from_documents(docs, model=model, embed_model=embed_model)
        index.storage_context.persist(persist_dir=storage_dir)
    else:
        print("Loading existing index...")
        storage_context = StorageContext.from_defaults(persist_dir=storage_dir)
        index = load_index_from_storage(storage_context, embed_model=embed_model)

    return index.as_retriever()

Testez le récupérateur :

from llama_index.llms.google_genai import GoogleGenAI

model = GoogleGenAI(
    model=model,
    **model_kwargs
)
retriever = retriever_builder(model)
retrieved_response = retriever.retrieve("What is Paul Graham's life in College?")

La réponse récupérée doit être semblable à ce qui suit :

[
  NodeWithScore(
    node=TextNode(
      id_='692a5d5c-cd56-4ed0-8e29-ecadf6eb9933',
      embedding=None,
      metadata={'file_path': '/content/data/paul_graham/paul_graham_essay.txt', 'file_name': 'paul_graham_essay.txt', 'file_type': 'text/plain', 'file_size': 75042, 'creation_date': '2025-03-24', 'last_modified_date': '2025-03-24'},
      excluded_embed_metadata_keys=['file_name', 'file_type', 'file_size', 'creation_date', 'last_modified_date', 'last_accessed_date'],
      excluded_llm_metadata_keys=['file_name', 'file_type', 'file_size', 'creation_date', 'last_modified_date', 'last_accessed_date'],
      relationships={
        <NodeRelationship.SOURCE: '1'>: RelatedNodeInfo(node_id='3e1c4d73-1e1d-4e83-bd16-2dae24abb231', node_type='4', metadata={'file_path': '/content/data/paul_graham/paul_graham_essay.txt', 'file_name': 'paul_graham_essay.txt', 'file_type': 'text/plain', 'file_size': 75042, 'creation_date': '2025-03-24', 'last_modified_date': '2025-03-24'}, hash='0c3c3f46cac874b495d944dfc4b920f6b68817dbbb1699ecc955d1fafb2bf87b'), <NodeRelationship.PREVIOUS: '2'>: RelatedNodeInfo(node_id='782c5787-8753-4f65-85ed-c2833ea6d4d8', node_type='1', metadata={'file_path': '/content/data/paul_graham/paul_graham_essay.txt', 'file_name': 'paul_graham_essay.txt', 'file_type': 'text/plain', 'file_size': 75042, 'creation_date': '2025-03-24', 'last_modified_date': '2025-03-24'}, hash='b8e6463833887a8a2b13f1b5a623672819faedc1b725d9565ba003223628db0e'), <NodeRelationship.NEXT: '3'>: RelatedNodeInfo(node_id='f7d2cb7e-fa0c-40bf-b8e7-b888e36b87f9', node_type='1', metadata={}, hash='db7cc1a67fa3afd1e5f24c8c61583781ce6a00c444da8f25a5374468c17b7de0')
      },
      metadata_template='{key}: {value}',
      metadata_separator='\n',
      text='So I looked around to see what I could salvage from the wreckage of my plans, and there was Lisp...',
      mimetype='text/plain',
      start_char_idx=7166,
      end_char_idx=11549,
      metadata_separator='\n',
      text_template='{metadata_str}\n\n{content}'
    ),
    score=0.7403571819090398
  )
]

Pour utiliser le récupérateur dans LlamaIndexQueryPipelineAgent, ajoutez-le sous l'argument retriever_builder= :

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model=model,                          # Required.
    model_kwargs=model_kwargs,            # Optional.
    retriever_builder=retriever_builder,  # Optional.
)

Testez l'agent localement en exécutant des requêtes de test :

response = agent.query(
    input="What is Paul Graham's life in College?"
)

La réponse est une liste de nœuds sérialisable au format JSON avec des scores.

[{'node': {'id_': '692a5d5c-cd56-4ed0-8e29-ecadf6eb9933',
  'embedding': None,
  'metadata': {'file_path': '/content/data/paul_graham/paul_graham_essay.txt',
    'file_name': 'paul_graham_essay.txt',
    'file_type': 'text/plain',
    'file_size': 75042,
    'creation_date': '2025-03-12',
    'last_modified_date': '2025-03-12'},
  'excluded_embed_metadata_keys': ['file_name',
    'file_type',
    'file_size',
    'creation_date',
    'last_modified_date',
    'last_accessed_date'],
  'excluded_llm_metadata_keys': ['file_name',
    'file_type',
    'file_size',
    'creation_date',
    'last_modified_date',
    'last_accessed_date'],
  'relationships': {'1': {'node_id': '07ee9574-04c8-46c7-b023-b22ba9558a1f',
    'node_type': '1',
    'metadata': {},
    'hash': '44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a',
    'class_name': 'RelatedNodeInfo'},
    '2': {'node_id': 'ac7e54aa-6fff-40b5-a15e-89c5eb234936',
    'node_type': '1',
    'metadata': {'file_path': '/content/data/paul_graham/paul_graham_essay.txt',
      'file_name': 'paul_graham_essay.txt',
      'file_type': 'text/plain',
      'file_size': 75042,
      'creation_date': '2025-03-12',
      'last_modified_date': '2025-03-12'},
    'hash': '755327a01efe7104db771e4e6f9683417884ea6895d878da882d2b21a6b66442',
    'class_name': 'RelatedNodeInfo'},
    '3': {'node_id': '3a04be27-ac46-4acd-a8c6-031689508982',
    'node_type': '1',
    'metadata': {},
    'hash': 'db7cc1a67fa3afd1e5f24c8c61583781ce6a00c444da8f25a5374468c17b7de0',
    'class_name': 'RelatedNodeInfo'}},
  'metadata_template': '{key}: {value}',
  'metadata_separator': '\n',
  'text': 'So I looked around to see what I could salvage from the wreckage of my plans, and there was Lisp...',
  'mimetype': 'text/plain',
  'start_char_idx': 7164,
  'end_char_idx': 11547,
  'metadata_separator': '\n',
  'text_template': '{metadata_str}\n\n{content}',
  'class_name': 'TextNode'},
  'score': 0.25325886336265013,
  'class_name': 'NodeWithScore'}
]

Définir et utiliser un synthétiseur de réponses

Après avoir défini votre modèle et votre récupérateur, définissez le synthétiseur de réponses qui génère une réponse à partir d'un LLM à l'aide d'une requête utilisateur et d'un ensemble donné de blocs de texte. Vous pouvez utiliser la fonction get_response_synthesizer par défaut ou configurer le mode de réponse.

Définissez un synthétiseur de réponses qui renvoie la réponse :

def response_synthesizer_builder(model, response_synthesizer_kwargs=None):
    from llama_index.core.response_synthesizers import SimpleSummarize

    return SimpleSummarize(llm=model)

Testez la fonction :

response_synthesizer = response_synthesizer_builder(model=model)
response = response_synthesizer.get_response(
    "What is Paul Graham's life in College?",
    [node.model_dump_json() for node in retrieved_response],
)

La sortie devrait ressembler à ce qui suit :

"While in a PhD program for computer science, he took art classes and worked on a book about Lisp hacking. He applied to art schools, got accepted to RISD, and later got an invitation to take the entrance exam at the Accademia di Belli Arti in Florence. He was accepted to both. He attended the Accademia, but was disappointed by the lack of instruction."

Pour utiliser le synthétiseur de réponses dans LlamaIndexQueryPipelineAgent, ajoutez-le sous l'argument response_synthesizer_builder= :

from vertexai.preview import reasoning_engines

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model=model,                                                    # Required.
    model_kwargs=model_kwargs,                                      # Optional.
    retriever_builder=retriever_builder,                            # Optional.
    response_synthesizer_builder=response_synthesizer_builder,      # Optional.
)

Testez le pipeline de requêtes RAG complet en local en exécutant des requêtes de test :

response = agent.query(
    input="What is Paul Graham's life in College?"
)

La réponse est un dictionnaire semblable à celui-ci :

{
  'response': "While in college, he was drawn to McCarthy's 1960 Lisp, although he didn't fully grasp the reasons for his interest at the time. He also had a brief encounter with surplus Xerox Dandelions in the computer lab but found them too slow for his liking. \n",
  'source_nodes': [
    '{"node":{"id_":"95889c30-53c7-43d0-bf91-930dbb23bde6"...,"score":0.7077213268404997,"class_name":"NodeWithScore"}'
  ],
  'metadata': {
    '95889c30-53c7-43d0-bf91-930dbb23bde6': {
      'file_path': '/content/data/paul_graham/paul_graham_essay.txt',
      'file_name': 'paul_graham_essay.txt',
      'file_type': 'text/plain',
      'file_size': 75042,
      'creation_date': '2025-03-25',
      'last_modified_date': '2025-03-25'
    }
  }
}

(Facultatif) Personnaliser le modèle de prompt

Les modèles de prompt traduisent les entrées utilisateur en instructions de modèle, ce qui permet de guider les réponses pour obtenir une sortie cohérente et pertinente sur le plan contextuel. Pour en savoir plus, consultez Prompts.

Le modèle de prompt par défaut est organisé de manière séquentielle dans les sections suivantes :

Section	Description
(Facultatif) Instruction système	Instructions pour l'agent à appliquer pour toutes les requêtes.
Entrée utilisateur	Requête de l'utilisateur à laquelle l'agent doit répondre.

Le modèle de prompt par défaut est généré si vous créez l'agent sans spécifier votre propre modèle de prompt. Il se présente comme suit :

from llama_index.core import prompts
from llama_index.core.base.llms import types

message_templates = [
  types.ChatMessage(role=types.MessageRole.SYSTEM, content=system_instruction),
  types.ChatMessage(role=types.MessageRole.USER, content="{input}"),
]
prompts.ChatPromptTemplate(message_templates=message_templates)

Vous pouvez utiliser le modèle de prompt complet lorsque vous instanciez l'agent dans l'exemple suivant :

  from vertexai.preview import reasoning_engines

  system_instruction = "I help to find what is Paul Graham's life in College"

  agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
      model=model,
      system_instruction=system_instruction,
  )

Vous pouvez remplacer le modèle de prompt par défaut par votre propre modèle de prompt et l'utiliser lors de la création de l'agent :

prompt_str = "Please answer {question} about {name}"
prompt_tmpl = PromptTemplate(prompt_str)

from vertexai.preview import reasoning_engines
agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
    model = model,
    prompt = prompt_tmpl,
)

agent.query(
    input={
        "name": "Paul Graham",
        "question": "What is the life in college?",
    }
)

(Facultatif) Personnaliser l'orchestration

Tous les composants LlamaIndexQueryPipeline implémentent l'interface Query Component, qui fournit des schémas d'entrée et de sortie pour l'orchestration. La classe LlamaIndexQueryPipelineAgent nécessite la création d'un exécutable pour qu'il puisse répondre aux requêtes. Par défaut, LlamaIndexQueryPipelineAgent crée une chaîne séquentielle ou un graphe orienté acyclique (DAG) à l'aide de Query Pipeline.

Vous pouvez personnaliser l'orchestration si vous souhaitez effectuer l'une des opérations suivantes :

Implémenter un agent qui étend le pipeline RAG (par exemple, en étendant un module Prompt, Model, Retriever ou Response Synthesizer existant à Query Engine, Query Transformer, Output Parsers, Postprocessor/Rerankers ou Custom Query Component).
Inviter l'agent à utiliser ReAct pour exécuter des outils et annoter chaque étape en indiquant pourquoi il l'a effectuée. Pour ce faire, remplacez l'exécutable par défaut lors de la création de LlamaIndexQueryPipelineAgent en spécifiant l'argument runnable_builder= :
```
from typing import Optional
from llama_index.core.llms import function_calling

def runnable_builder(
    model: function_calling.FunctionCallingLLM,
    *,
    system_instruction: Optional[str] = None,
    prompt: Optional[query.QUERY_COMPONENT_TYPE] = None,
    retriever: Optional[query.QUERY_COMPONENT_TYPE] = None,
    response_synthesizer: Optional[query.QUERY_COMPONENT_TYPE] = None,
    runnable_kwargs: Optional[Mapping[str, Any]] = None,
):
```
Où :
- model correspond au modèle de chat renvoyé par model_builder (voir Définir et configurer un modèle).
- retriever et retriever_kwargs correspondent au récupérateur et aux configurations à utiliser (voir Définir un récupérateur) ;
- response_synthesizer et response_synthesizer_kwargs correspondent au synthétiseur de réponses et aux configurations à utiliser (voir Définir un synthétiseur de réponses) ;
- system_instruction et prompt correspondent à la configuration du prompt (voir Personnaliser le modèle de prompt) ;
- agent_executor_kwargs et runnable_kwargs sont les arguments de mot clé que vous pouvez utiliser pour personnaliser l'exécutable.

Vous pouvez personnaliser la logique d'orchestration à l'aide d'un pipeline personnalisé ou de ReAct :

Pipeline personnalisé

Pour fournir un module supplémentaire (tel qu'un post-processeur) à l'agent, remplacez le runnable_builder pour LlamaIndexQueryPipelineAgent.

Définissez un post-processeur :

def post_processor_builder():
  from llama_index.core.postprocessor import SimilarityPostprocessor

  # similarity postprocessor: filter nodes below 0.7 similarity score
  return SimilarityPostprocessor(similarity_cutoff=0.7)

def runnable_with_postprocessor_builder(
    model, runnable_kwargs, **kwargs
):
  from llama_index.core.query_pipeline import QueryPipeline

  pipeline = QueryPipeline(**runnable_kwargs)
  pipeline_modules = {
      "retriever": retriever_builder(model),
      "postprocessor": post_processor_builder(),
  }
  pipeline.add_modules(pipeline_modules)
  pipeline.add_link("retriever", "postprocessor")

  return pipeline

agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
  model=model,
  runnable_builder=runnable_with_postprocessor_builder,
)

Interrogez l'agent :

result = agent.query(input="What is Paul Graham's life in College?")