Mengembangkan agen Pipeline Kueri LlamaIndex

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Halaman ini menunjukkan cara mengembangkan agen menggunakan template LlamaIndex Query Pipelines (class LlamaIndexQueryPipelineAgent di Vertex AI SDK untuk Python). Agen ini dirancang untuk menjawab pertanyaan menggunakan Retrieval-Augmented Generation (RAG), seperti kueri berikut: "Bagaimana kehidupan Paul Graham di perguruan tinggi?"

Gunakan langkah-langkah berikut untuk mengembangkan agen menggunakan LlamaIndex Query Pipelines:

1. Menentukan dan mengonfigurasi model
2. Menentukan dan menggunakan retriever
3. Menentukan dan menggunakan synthesizer respons
4. (Opsional) Menyesuaikan template perintah
5. (Opsional) Menyesuaikan orkestrasi

Sebelum memulai

Pastikan lingkungan Anda sudah disiapkan dengan mengikuti langkah-langkah di Menyiapkan lingkungan.

Menentukan dan mengonfigurasi model

Tentukan dan konfigurasikan model untuk digunakan oleh agen LlamaIndex Query Pipelines Anda.

1. Tentukan versi model:

   model = "gemini-1.5-flash-001"
   

2. (Opsional) Tentukan parameter model:

   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. Buat LlamaIndexQueryPipelineAgent menggunakan konfigurasi model berikut:

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

4. Jika Anda menjalankannya di lingkungan interaktif (seperti terminal atau notebook Colab), Anda dapat membuat kueri agen:

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

   Anda akan melihat respons seperti berikut:

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

(Opsional) Menyesuaikan model

Template LlamaIndexQueryPipelineAgent menggunakan Google GenAI secara default untuk memberikan akses ke semua model dasar yang tersedia di Google Cloud. Untuk menggunakan model yang tidak tersedia melalui Google GenAI, tentukan model_builder= sebagai berikut:

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

Untuk mengetahui daftar model chat yang didukung di LlamaIndexQueryPipeline dan kemampuannya, lihat Integrasi LLM yang tersedia. Setiap model chat menggunakan kumpulan nilai yang didukungnya sendiri untuk model= dan model_kwargs=.

from vertexai.preview import reasoning_engines

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

Menentukan dan menggunakan pengambil

Setelah menentukan model, tentukan pengambil yang digunakan model untuk penalaran. Pengambil dapat dibuat di atas indeks, tetapi juga dapat ditentukan secara komprehensif. Anda harus menguji retriever secara lokal.

1. Tentukan retriever yang menampilkan dokumen dan skor kesamaan yang relevan:

   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. Uji pengambil:

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

   Respons yang diambil akan mirip dengan berikut ini:

   [
     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. Untuk menggunakan pengambil di dalam template LlamaIndexQueryPipelineAgent, tambahkan di bagian argumen 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. Uji agen secara lokal dengan menjalankan kueri pengujian:

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

   Responsnya adalah daftar node yang dapat diserialisasi JSON dengan skor.

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

Menentukan dan menggunakan synthesizer respons

Setelah menentukan model dan pengambil, tentukan synthesizer respons yang menghasilkan respons dari LLM menggunakan kueri pengguna dan kumpulan potongan teks tertentu. Anda dapat menggunakan get_response_synthesizer default atau mengonfigurasi mode respons.

1. Tentukan synthesizer respons yang menampilkan jawaban:

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

2. Uji fungsi:

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

   Responsnya akan mirip dengan berikut ini:

   "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. Untuk menggunakan synthesizer respons di dalam template LlamaIndexQueryPipeline, tambahkan di bagian argumen 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. Uji pipeline kueri RAG lengkap secara lokal dengan menjalankan kueri pengujian:

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

   Responsnya adalah kamus yang mirip dengan berikut ini:

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

(Opsional) Menyesuaikan template dialog

Template perintah menerjemahkan input pengguna menjadi petunjuk model, yang memandu respons untuk output yang relevan secara kontekstual dan koheren. Lihat Perintah untuk mengetahui detailnya.

Template perintah default diatur secara berurutan ke dalam bagian berikut:

Template perintah default dibuat jika Anda membuat agen tanpa menentukan template perintah Anda sendiri, dan terlihat seperti berikut:

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)

Anda dapat menggunakan template perintah lengkap saat membuat instance agen dalam contoh berikut:

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

Anda dapat mengganti template perintah default dengan template perintah Anda sendiri, dan menggunakannya saat membuat agen:

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

(Opsional) Menyesuaikan orkestrasi

Semua komponen LlamaIndexQueryPipeline mengimplementasikan antarmuka Komponen Kueri, yang menyediakan skema input dan output untuk orkestrasi. LlamaIndexQueryPipelineAgent memerlukan runnable yang akan di-build agar dapat merespons kueri. Secara default, LlamaIndexQueryPipelineAgent membuat rantai berurutan atau Directed Acyclic Graph (DAG) menggunakan Query Pipeline.

Anda dapat menyesuaikan orkestrasi jika ingin melakukan salah satu hal berikut:

• Terapkan agen yang memperluas pipeline RAG (seperti memperluas modul Prompt, Model, Pengambil, Sintetizer Respons yang ada ke Mesin Kueri, Query Transformer, Output Parser, Postprocessor/Reranker, atau Komponen Kueri Kustom).

• Minta agen menggunakan ReAct untuk menjalankan alat dan anotasi setiap langkah dengan komentar tentang alasan agen melakukan langkah tersebut. Untuk melakukannya, ganti runnable default saat membuat LlamaIndexQueryPipelineAgent dengan menentukan argumen 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,
  ):
  

  Dengan keterangan:

  • model sesuai dengan model chat yang ditampilkan dari model_builder (lihat Menentukan dan mengonfigurasi model).
  • retriever dan retriever_kwargs sesuai dengan pengambil dan konfigurasi yang akan digunakan (lihat Menentukan pengambil).
  • response_synthesizer dan response_synthesizer_kwargs sesuai dengan synthesizer respons dan konfigurasi yang akan digunakan (lihat Menentukan synthesizer respons).
  • system_instruction dan prompt sesuai dengan konfigurasi perintah (lihat Menyesuaikan template perintah).
  • agent_executor_kwargs dan runnable_kwargs adalah argumen kata kunci yang dapat Anda gunakan untuk menyesuaikan runnable.

Anda dapat menyesuaikan logika orkestrasi menggunakan pipeline kustom atau ReAct:

Langkah berikutnya

• Mengevaluasi agen.
• Men-deploy agen.
• Memecahkan masalah pengembangan agen.
• Dapatkan dukungan.