Container Service for Kubernetes:Terapkan aplikasi agen sebagai layanan Knative

Cara kerja

Perintah agentscope deploy knative menyederhanakan proses kompleks containerisasi aplikasi agen dan penerapannya ke kluster. Alur kerjanya adalah sebagai berikut:

1. Mengemas aplikasi: Mengemas kode aplikasi agen Python yang ditentukan, dependensinya (requirements.txt), dan variabel lingkungan.

2. Membuat gambar: Membuat gambar kontainer yang mencakup aplikasi agen di lingkungan Docker lokal Anda, berdasarkan gambar dasar yang ditentukan.

3. Mendorong gambar: Mendorong gambar yang telah dibuat ke registri gambar kontainer tertentu, seperti Container Registry (ACR).

4. Menyebarkan layanan: Menghasilkan dan menerapkan manifes Knative Service (ksvc) di kluster target. Knative kemudian menggunakan manifes ini untuk membuat Deployment dan Pod, serta secara otomatis mengonfigurasi routing jaringan, load balancing, dan kebijakan auto scaling.

Sebelum memulai

• Anda telah menyebarkan komponen Knative di kluster.

• Anda telah menyebarkan Knative di kluster ACS.

• Docker telah diinstal dan berjalan di mesin lokal Anda untuk membangun gambar kontainer.

• Anda telah menginstal AgentScope Runtime menggunakan perintah pip.

  # Instalasi dasar
  pip install agentscope-runtime>=1.1.0
  # Dependensi untuk penerapan Kubernetes
  pip install "agentscope-runtime[ext]>=1.1.0"

Langkah 1: Buat proyek agen

Jika Anda belum memiliki aplikasi agen, gunakan struktur file dan kode contoh berikut.

1. Buat struktur direktori proyek:

   my-agent-project/
   ├── app_agent.py          # File utama untuk aplikasi agen
   ├── requirements.txt      # Dependensi Python (opsional)
   └── .env                  # Variabel lingkungan (opsional)

2. Tulis kode agen di file app_agent.py.

   Kode berikut membuat agen yang menggunakan model Qwen dan mendukung eksekusi kode serta percakapan multi-putaran.

   # -*- coding: utf-8 -*-
   import os
   from contextlib import asynccontextmanager
   from fastapi import FastAPI
   from agentscope.agent import ReActAgent
   from agentscope.formatter import DashScopeChatFormatter
   from agentscope.model import DashScopeChatModel
   from agentscope.pipeline import stream_printing_messages
   from agentscope.tool import Toolkit, execute_python_code
   from agentscope.memory import InMemoryMemory
   from agentscope.session import JSONSession
   from agentscope_runtime.engine.app import AgentApp
   from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
   @asynccontextmanager
   async def lifespan(app: FastAPI):
       """Inisialisasi layanan."""
       app.state.session = JSONSession(
           save_dir="./",  # Direktori untuk menyimpan semua file sesi
       )
       try:
           yield
       finally:
           print("AgentApp is shutting down...")
   # Buat AgentApp
   agent_app = AgentApp(
       app_name="MyAssistant",
       app_description="A helpful assistant agent",
       lifespan=lifespan,
   )
   @agent_app.query(framework="agentscope")
   async def query_func(
       self,
       msgs,
       request: AgentRequest = None,
       **kwargs,
   ):
       """Proses kueri pengguna."""
       session_id = request.session_id
       user_id = request.user_id
       # Buat toolkit dengan eksekusi Python
       toolkit = Toolkit()
       toolkit.register_tool_function(execute_python_code)
       # Buat agen
       agent = ReActAgent(
           name="MyAssistant",
           model=DashScopeChatModel(
               "qwen-turbo",
               api_key=os.getenv("DASHSCOPE_API_KEY"),
               enable_thinking=True,
               stream=True,
           ),
           sys_prompt="You're a helpful assistant.",
           toolkit=toolkit,
           memory=InMemoryMemory(),
           formatter=DashScopeChatFormatter(),
       )
       agent.set_console_output_enabled(False)
       await agent_app.state.session.load_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
       async for msg, last in stream_printing_messages(
           agents=[agent],
           coroutine_task=agent(msgs),
       ):
           yield msg, last
       await agent_app.state.session.save_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
   if __name__ == "__main__":
       agent_app.run()

Langkah 2: Terapkan aplikasi agen

Gunakan perintah agentscope deploy untuk menerapkan aplikasi agen lokal Anda sebagai layanan Knative.

Langkah 3: Akses agen yang telah diterapkan

1. Dapatkan gerbang akses.

   1. Pada halaman ACK Clusters, klik nama kluster Anda. Di panel navigasi kiri, klik Applications > Knative.

   2. Login ke Konsol ACS. Di panel navigasi kiri, klik Clusters.

   3. Pada halaman Clusters, klik nama kluster target. Di panel navigasi kiri, pilih Applications > Knative.

   4. Pada halaman Services atau Component management, dapatkan Gateway.

      Alamat IP Access Gateway (misalnya, 120.xxx.159) berada di bagian bawah halaman. Sebelum mengakses layanan, Anda harus mengarahkan domain layanan ke alamat IP ini.

2. Kirim permintaan ke layanan agen menggunakan perintah curl.

   Ganti 115.29.xxx.xxx dengan alamat IP gerbang akses dan ganti nilai Host dengan URL akses yang Anda peroleh sebelumnya.

   curl -i -X POST "http://115.29.xxx.xxx:80/process" \
     -H "Content-Type: application/json" \
     -H "Host: agent-03e*****.default.example.com" \
     -d '{
       "input": [
         {
           "role": "user",
           "content": [
             {
               "type": "text",
               "text": "Hello, how are you?"
             }
           ]
         }
       ],
       "session_id": "123"
     }'

3. Lihat hasilnya. Tanggapan tersebut mengalirkan proses pemikiran agen dan output akhirnya.

Langkah 4: Amati auto scaling

• Scale-down: Setelah periode tidak aktif, Knative secara otomatis menskalakan Pod layanan ke nol untuk menghemat resource. Anda dapat mengamati perubahan pada Pod dengan menjalankan perintah berikut:

  # Pantau terus-menerus Pod di namespace yang ditentukan
  kubectl get pods -n default -w

  Atau, pada halaman Knative, klik Services, lalu klik nama layanan. Anda dapat melihat status berjalan Pod untuk revisi saat ini di bagian bawah halaman.

  Pada tab Revision information, kolom Ready/requested Pods untuk revisi saat ini menunjukkan 0/0, yang mengonfirmasi bahwa Pod telah diskalakan ke nol.

• Scale-up: Saat permintaan baru tiba, Knative secara otomatis memulai Pod baru dalam hitungan detik untuk menangani permintaan tersebut.

Rekomendasi produksi

• Pertahankan state: InMemoryStateService dan InMemorySessionHistoryService yang disebutkan dalam contoh akan kehilangan seluruh state dan riwayat percakapan ketika Pod dimulai ulang, sehingga tidak cocok untuk produksi. Untuk penerapan produksi, beralihlah ke implementasi yang didukung Redis atau solusi penyimpanan persisten lainnya.

• Kelola rahasia: Jangan meneruskan informasi sensitif seperti API_KEY langsung melalui command line atau hard-code di aplikasi Anda. Gunakan Kubernetes Secrets dan mount sebagai variabel lingkungan di kontainer melalui konfigurasi Knative Service.

• Rencanakan resource: Berdasarkan beban kerja yang diharapkan, lakukan uji stres dan konfigurasikan parameter seperti --cpu-request, --cpu-limit, --memory-request, dan --memory-limit untuk memastikan kinerja dan stabilitas layanan.

• Tingkatkan observabilitas: Konfigurasikan pengumpulan log (seperti Log Service) dan pemantauan dengan alert (seperti Application Real-Time Monitoring Service (ARMS)) untuk memecahkan masalah dan memantau kesehatan layanan.

Operasi terkait

• Perbarui agen: Setelah memodifikasi kode, jalankan kembali perintah agentscope deploy knative dengan tag gambar baru (misalnya, --image-tag v1.1) untuk melakukan pembaruan bergulir.

• Hapus instalasi agen:

  # Ganti <resource-name> dan <namespace> dengan nilai aktual Anda
  kubectl delete ksvc <resource-name> -n <namespace>

  Operasi ini hanya menghapus layanan di Kubernetes. Gambar kontainer yang telah didorong ke registri kontainer tidak dihapus.