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

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

Pour développer un agent à l'aide de pipelines de requêtes LlamaIndex, procédez comme suit:

1. Définir et configurer un modèle
2. Définir et utiliser un récupérateur
3. Définir et utiliser un synthétiseur de réponses
4. (Facultatif) Personnaliser le modèle d'invite
5. (Facultatif) Personnaliser l'orchestration

Avant de commencer

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

Définir et configurer un modèle

Définissez et configurez un modèle à utiliser par votre agent de pipeline de requêtes LlamaIndex.

1. Définissez la version du modèle:

   model = "gemini-2.0-flash"
   

2. (Facultatif) Spécifiez les paramètres de 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,
   }
   

3. 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.
   )
   

4. Si vous exécutez votre code dans 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 non 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 la section Intégrations de LLM disponibles. Chaque modèle de chat utilise son propre ensemble de valeurs acceptées pour model= et model_kwargs=.

from vertexai.preview import reasoning_engines

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

Définir et utiliser un récupérateur

Une fois votre modèle défini, définissez le récupérateur qu'il utilise pour le raisonnement. Un récupéréur peut être créé sur la base d'index, mais peut également être défini de manière complète. Vous devez tester votre récupérateur en local.

1. Définissez un récupérateur qui renvoie des documents pertinents et des 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="textembedding-gecko@003", 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()
   

2. 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 devrait ressembler à 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
     )
   ]
   

3. Pour utiliser le récupérateur dans le modèle 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.
   )
   

4. 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 sérialisable JSON de nœuds 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éponse

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

1. Définissez un synthétiseur de réponse 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)
   

2. 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."
   

3. Pour utiliser le synthétiseur de réponse dans le modèle LlamaIndexQueryPipeline, 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.
   )
   

4. 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 d'invite

Les modèles de requêtes traduisent les entrées utilisateur en instructions de modèle, guidant les réponses pour obtenir des résultats pertinents et cohérents en fonction du contexte. Pour en savoir plus, consultez la section Invites.

Le modèle d'invite par défaut est organisé de manière séquentielle en sections:

Le modèle de requête par défaut est généré si vous créez l'agent sans spécifier votre propre modèle de requête. 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 requête 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 requête par défaut par votre propre modèle de requête 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. Le 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émentez un agent qui étend le pipeline RAG (par exemple, en étendant un module d'invite, de modèle, de récupération ou de synthèse de réponse existant au moteur de requête, au transformateur de requête, aux analyseurs de sortie, aux post-traitements/reclassements ou au composant de requête personnalisé).

• Demandez à l'agent à l'aide de ReAct d'exécuter des outils et d'annoter chaque étape avec des commentaires expliquant pourquoi il a effectué cette étape. 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 de la requête (voir la section Personnaliser le modèle de requête).
  • 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:

Étape suivante

• Évaluer un agent
• Déployez un agent.
• Résoudre les problèmes de développement d'un agent
• Accédez à l'assistance.