LlamaIndex Query Pipeline-Agent erstellen

Mit der Agent Runtime können Sie Agenten mit der Vorlage „LlamaIndex Query Pipelines“ entwickeln und bereitstellen. Mit der Klasse LlamaIndexQueryPipelineAgent im Agent Platform SDK können Sie Agenten erstellen, die für Retrieval Augmented Generation (RAG) entwickelt wurden.

In diesem Dokument wird erläutert, wie Sie einen LlamaIndex Query Pipeline-Agenten entwickeln, einschließlich der Definition des Modells, der Einrichtung eines Retrievers und der Synthese von Antworten.

Weitere Informationen zum Verwalten Ihrer bereitgestellten Agenten finden Sie unter Bereitgestellte Agenten verwalten.

Hinweis

Richten Sie Ihre Umgebung ein, indem Sie die Schritte unter Umgebung einrichten ausführen.

Modell definieren und konfigurieren

Definieren und konfigurieren Sie ein Modell, das von Ihrem LlamaIndex Query Pipeline-Agenten verwendet werden soll:

1. Geben Sie das Modell an, das Sie verwenden möchten:

   model = "gemini-3.5-flash"
   

2. Optional: Geben Sie Modellparameter an:

   model_kwargs = {
       # vertexai_config (dict): By providing the region and project_id parameters,
       # you can enable model usage through Agent Platform.
       "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. Erstellen Sie einen LlamaIndexQueryPipelineAgent mit den folgenden Modellkonfigurationen:

   from vertexai.preview import reasoning_engines
   
   agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
       model=model,                # Required.
       model_kwargs=model_kwargs,  # Optional.
   )
   

4. Wenn Sie in einer interaktiven Umgebung arbeiten (z. B. im Terminal oder in einem Colab-Notebook), können Sie den Agenten abfragen:

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

   Sie sollten eine Antwort ähnlich der folgenden erhalten:

   {'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': {}}
   

Optional: Modell anpassen

Die LlamaIndexQueryPipelineAgent Vorlage verwendet Google GenAI standardmäßig, um Zugriff auf alle in Google Cloudverfügbaren Foundation Models zu ermöglichen. Wenn Sie ein Modell verwenden möchten, das nicht über Google GenAI verfügbar ist, definieren Sie model_builder= so:

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

Eine Liste der in LlamaIndexQueryPipeline unterstützten Chatmodelle und ihrer Funktionen finden Sie unter Verfügbare LLM Integrationen. Jedes Chatmodell verwendet eigene unterstützte Werte für model= und model_kwargs=.

from vertexai.preview import reasoning_engines

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

Retriever definieren und verwenden

Nachdem Sie Ihr Modell definiert haben, definieren Sie den Retriever, den Ihr Modell für die Logik verwendet. Ein Retriever kann auf der Grundlage von Indexenerstellt werden, kann aber auch umfassenddefiniert werden. Sie sollten Ihren Retriever lokal testen.

1. Definieren Sie einen Retriever, der relevante Dokumente und Ähnlichkeitswerte zurückgibt:

   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()
   

2. Testen Sie den Retriever:

   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?")
   

   Die abgerufene Antwort sollte in etwa so aussehen:

   [
     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. Wenn Sie den Retriever in LlamaIndexQueryPipelineAgent verwenden möchten, fügen Sie ihn unter dem Argument retriever_builder= hinzu:

   from vertexai.preview import reasoning_engines
   
   agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
       model=model,                          # Required.
       model_kwargs=model_kwargs,            # Optional.
       retriever_builder=retriever_builder,  # Optional.
   )
   

4. Testen Sie den Agenten lokal, indem Sie Testabfragen durchführen:

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

   Die Antwort ist eine JSON-serialisierbare Liste von Knoten mit Werten.

   [{'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'}
   ]
   

Antwortsynthesizer definieren und verwenden

Nachdem Sie Ihr Modell und Ihren Retriever definiert haben, definieren Sie den Antwortsynthesizer, der mit einer Nutzerabfrage und einer bestimmten Anzahl von Textblöcken eine Antwort von einem LLM generiert. Sie können den Standard-get_response_synthesizer verwenden oder den Antwortmoduskonfigurieren.

1. Definieren Sie einen Antwortsynthesizer, der die Antwort zurückgibt:

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

2. Die Funktion testen:

   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],
   )
   

   Die Antwort sollte in etwa so aussehen:

   "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. Wenn Sie den Antwortsynthesizer in LlamaIndexQueryPipelineAgent verwenden möchten, fügen Sie ihn unter dem Argument response_synthesizer_builder= hinzu:

   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. Testen Sie die vollständige RAG-Abfragepipeline lokal, indem Sie Testabfragen ausführen:

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

   Die Antwort ist ein Dictionary, das in etwa so aussieht:

   {
     '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'
       }
     }
   }
   

Optional: Promptvorlage anpassen

Promptvorlagen übersetzen Nutzereingaben in Modellanweisungen und steuern Antworten für kontextbezogene und kohärente Ausgaben. Weitere Informationen finden Sie unter Prompts.

Die Standard-Prompt-Vorlage ist sequenziell in die folgenden Abschnitte unterteilt:

Die Standard-Prompt-Vorlage wird generiert, wenn Sie den Agenten erstellen, ohne eine eigene Prompt-Vorlage anzugeben. Sie sieht so aus:

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)

Sie können die vollständige Prompt-Vorlage verwenden, wenn Sie den Agenten im folgenden Beispiel instanziieren:

  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,
  )

Sie können die Standard-Promptvorlage mit Ihrer eigenen Promptvorlage überschreiben und sie beim Erstellen des Agenten verwenden:

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?",
    }
)

Optional: Orchestrierung anpassen

Alle LlamaIndexQueryPipeline Komponenten implementieren die Query Component Schnittstelle, die Eingabe- und Ausgabeschemas für die Orchestrierung bereitstellt. Für die LlamaIndexQueryPipelineAgent Klasse muss ein ausführbares Programm erstellt werden, damit sie auf Abfragen reagieren kann. Standardmäßig erstellt LlamaIndexQueryPipelineAgent mit Query Pipeline eine sequenzielle Kette oder einen gerichteten azyklischen Graphen (Directed Acyclic Graph, DAG).

Möglicherweise möchten Sie die Orchestrierung anpassen, wenn Sie eine der folgenden Aktionen ausführen möchten:

• Implementieren Sie einen Agenten, der die RAG-Pipeline erweitert (z. B. durch Erweitern eines vorhandenen Prompt-, Modell-, Retriever- oder Antwortsynthesizer-Moduls zu Query Engine, Query Transformer, Output Parsers, Postprocessor/Rerankers oder Custom Query Component).

• Fordern Sie den Agenten mit ReAct auf, Tools auszuführen und jeden Schritt mit Kommentaren zu versehen, warum er diesen Schritt ausgeführt hat. Überschreiben Sie dazu beim Erstellen von LlamaIndexQueryPipelineAgent das ausführbare Standardprogramm, indem Sie das runnable_builder= Argument angeben:

  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,
  ):
  

  Wobei:

  • model entspricht dem Chatmodell, das von model_builder zurückgegeben wird (siehe Modell definieren und konfigurieren).
  • retriever und retriever_kwargs entsprechen dem zu verwendenden Retriever und den zu verwendenden Konfigurationen (siehe Retriever definieren).
  • response_synthesizer und response_synthesizer_kwargs entsprechen dem Antwortsynthesizer und den zu verwendenden Konfigurationen (siehe Antwortsynthesizer definieren).
  • system_instruction und prompt entsprechen der Promptkonfiguration (siehe Promptvorlage anpassen).
  • agent_executor_kwargs und runnable_kwargs sind die Schlüsselwortargumente, mit denen Sie das ausführbare Programm anpassen können.

Sie können die Orchestrierungslogik mit einer benutzerdefinierten Pipeline oder ReAct anpassen:

Nächste Schritte