Sesi penerjemah kode tanpa server di Azure Container Apps

Sesi dinamis Azure Container Apps menyediakan akses yang cepat dan dapat diskalakan ke penerjemah kode. Setiap sesi penerjemah kode sepenuhnya diisolasi oleh batas Hyper-V dan dirancang untuk menjalankan kode yang tidak tepercaya.

Menggunakan untuk sesi penerjemah kode

Sesi penerjemah kode sangat ideal untuk skenario di mana Anda perlu menjalankan kode yang berpotensi berbahaya atau dapat membahayakan sistem host atau pengguna lain, seperti:

  • Kode yang dihasilkan oleh model bahasa besar (LLM).
  • Kode yang dikirimkan oleh pengguna akhir di aplikasi web atau SaaS.

Untuk kerangka kerja LLM populer seperti LangChain, LlamaIndex, dan Kernel Semantik, Anda dapat menggunakan alat dan plugin untuk mengintegrasikan aplikasi AI dengan sesi penerjemah kode.

Aplikasi Anda juga dapat diintegrasikan dengan sesi penerjemah kode dengan menggunakan REST API. API memungkinkan Anda untuk:

  • Jalankan kode dalam sesi dan ambil hasil.

  • Unggah dan unduh file ke dan dari sesi.

    Anda dapat mengunggah dan mengunduh file kode yang dapat dieksekusi atau file data yang dapat diproses kode Anda.

Sesi penerjemah kode bawaan mendukung skenario eksekusi kode yang paling umum tanpa mengharuskan Anda mengelola infrastruktur atau kontainer.

Jika Anda memerlukan kontrol penuh atas lingkungan eksekusi kode atau memiliki skenario berbeda yang memerlukan kotak pasir terisolasi, Anda dapat menggunakan sesi penerjemah kode kustom.

Kumpulan sesi penerjemah kode

Untuk menggunakan sesi penerjemah kode, Anda memerlukan sumber daya Azure yang disebut kumpulan sesi yang menentukan konfigurasi untuk sesi penerjemah kode.

Di kumpulan sesi, Anda dapat menentukan pengaturan seperti jumlah maksimum sesi bersamaan dan berapa lama sesi dapat diam sebelum sesi dihentikan.

Anda dapat membuat kumpulan sesi dengan menggunakan portal Microsoft Azure, Azure CLI, atau templat Azure Resource Manager. Setelah membuat kumpulan sesi, Anda dapat menggunakan titik akhir API manajemen kumpulan untuk mengelola dan menjalankan kode di dalam sesi.

Untuk informasi selengkapnya tentang cara membuat dan mengonfigurasi kumpulan sesi, lihat Menggunakan kumpulan sesi.

Eksekusi kode dalam sesi

Setelah Anda membuat kumpulan sesi, aplikasi Anda dapat berinteraksi dengan sesi di kumpulan dengan menggunakan integrasi dengan kerangka kerja LLM atau dengan menggunakan titik akhir API manajemen kumpulan secara langsung.

Pengidentifikasi sesi

Penting

Pengidentifikasi sesi adalah informasi sensitif. Anda perlu menggunakan proses aman untuk mengelola nilainya. Bagian dari proses ini adalah memastikan bahwa aplikasi Anda memastikan setiap pengguna atau penyewa hanya memiliki akses ke sesi mereka sendiri.

Kegagalan untuk mengamankan akses ke sesi dapat mengakibatkan penyalahgunaan atau akses tidak sah ke data yang disimpan dalam sesi pengguna Anda. Untuk informasi selengkapnya, lihat Pengidentifikasi sesi.

Saat berinteraksi dengan sesi di kumpulan, Anda menggunakan pengidentifikasi sesi untuk mereferensikan setiap sesi. Pengidentifikasi sesi adalah string yang Anda tentukan unik dalam kumpulan sesi. Jika Anda membuat aplikasi web, Anda dapat menggunakan ID pengguna. Jika Anda membuat chatbot, Anda dapat menggunakan ID percakapan.

Jika ada sesi yang sedang berjalan dengan pengidentifikasi, sesi akan digunakan kembali. Jika tidak ada sesi yang berjalan dengan pengidentifikasi, sesi baru akan dibuat secara otomatis.

Autentikasi

Autentikasi ditangani melalui token Microsoft Entra. Token Microsoft Entra yang valid dihasilkan oleh identitas yang termasuk dalam peran Azure ContainerApps Session Executor dan Kontributor pada kumpulan sesi.

Jika Anda menggunakan integrasi kerangka kerja LLM, kerangka kerja menangani pembuatan dan manajemen token untuk Anda. Pastikan bahwa aplikasi dikonfigurasi dengan identitas terkelola yang memiliki penetapan peran yang diperlukan pada kumpulan sesi.

Jika Anda menggunakan titik akhir API manajemen kumpulan secara langsung, Anda harus membuat token dan menyertakannya di Authorization header permintaan HTTP Anda. Selain penetapan peran yang disebutkan sebelumnya, token perlu berisi klaim audiens (aud) yang memiliki nilai https://dynamicsessions.io.

Untuk informasi selengkapnya, lihat Autentikasi dan otorisasi.

Bekerja dengan berkas

Anda dapat mengunggah dan mengunduh file, dan mencantumkan semua file dalam sesi penerjemah kode.

Karakter yang didukung

Nama file dan jalur hanya boleh menggunakan karakter yang didukung berikut:

  • Huruf besar dan huruf kecil: A-Z, a-z.
  • Digit: 0-9.
  • Karakter khusus: -, ,_ , ., @, $, &, =, ;, ,, #, %^, , (. ) (Jalur tidak boleh berisi ..)
  • Karakter Unicode: Termasuk karakter Tionghoa, Jepang, dan internasional lainnya.

Mengunggah file

Untuk mengunggah file ke sesi, kirim POST permintaan ke files titik akhir dalam permintaan data formulir multipihak. Sertakan data file dalam isi permintaan. File harus menyertakan nama file.

File yang diunggah disimpan dalam sistem file sesi di /mnt/data direktori.

Contoh berikut menunjukkan cara mengunggah file ke sesi.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <TOKEN>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Unduh sebuah file

Untuk mengunduh file dari direktori sesi /mnt/data , kirim GET permintaan ke files/{filename}/content titik akhir. Respons mencakup data file.

Contoh berikut menunjukkan cara memformat GET permintaan untuk mengunduh file.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>/content?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Dapatkan metadata file

Untuk mendapatkan metadata untuk file di direktori sesi /mnt/data, kirimkan permintaan GET ke endpoint files/{filename}. Respons mencakup properti file seperti ukuran dan waktu terakhir diubah.

Contoh berikut menunjukkan cara memformat GET permintaan untuk mengambil metadata file.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Daftar file

Untuk mencantumkan file dalam direktori sesi /mnt/data, kirimkan permintaan GET ke titik akhir files.

Contoh berikut menunjukkan cara mencantumkan file dalam direktori sesi.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Respons berisi daftar file dalam sesi.

Daftar berikut ini memperlihatkan sampel jenis respons yang dapat Anda harapkan saat meminta konten sesi.

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

Keamanan

Sesi penerjemah kode dirancang untuk menjalankan kode yang tidak tepercaya di lingkungan terisolasi untuk memastikan bahwa aplikasi dan data Anda tetap terlindungi.

Integrasi kerangka kerja LLM

Alih-alih menggunakan API manajemen kumpulan sesi secara langsung, Anda dapat menggunakan kerangka kerja LLM berikut, yang menyediakan integrasi dengan sesi penerjemah kode.

Kerangka kerja Paket Panduan
LangChain Python: langchain-azure-dynamic-sessions Tutorial
LlamaIndex Python: llama-index-tools-azure-code-interpreter Tutorial
Kernel Semantik Python: semantic-kernel (versi 0.9.8-b1 atau yang lebih baru) Tutorial

Titik akhir API Manajemen

Jika Anda tidak menggunakan integrasi kerangka kerja LLM, Anda dapat berinteraksi dengan kumpulan sesi secara langsung dengan menggunakan titik akhir API manajemen.

Menjalankan kode dalam sesi

Untuk menjalankan kode dalam sesi, kirimkan POST permintaan ke executions endpoint dengan kode yang akan dijalankan di dalam badan permintaan. Setiap eksekusi kode dibatasi hingga runtime maksimum 220 detik.

Contoh berikut mencetak Hello, world! di Python.

Sebelum Anda mengirim permintaan, ganti placeholder di antara tanda kurung <> dengan nilai yang menyesuaikan untuk kumpulan sesi dan pengidentifikasi sesi Anda.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/executions?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "print('Hello, world!')"
    }
}

Untuk menggunakan kembali sesi, tentukan pengidentifikasi sesi yang sama dalam permintaan berikutnya.

Mengunggah file ke sesi

Untuk mengunggah file ke sesi, kirim POST permintaan ke files titik akhir dalam permintaan data formulir multipihak. Sertakan data file dalam isi permintaan. File harus menyertakan nama file.

File yang diunggah disimpan dalam sistem file sesi di /mnt/data direktori.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer <TOKEN>

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="<FILE_NAME_AND_EXTENSION>"
Content-Type: application/octet-stream

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Catatan

Batas unggahan file adalah 128 MB. Jika batas ini terlampaui, Anda mungkin mendapatkan kesalahan HTTP 413.

Mengunduh file dari sesi

Untuk mengunduh file dari direktori sesi /mnt/data , kirim GET permintaan ke files/{filename}/content titik akhir. Respons mencakup data file.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>/content?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Dapatkan metadata file

Untuk mendapatkan metadata untuk file di direktori sesi /mnt/data, kirimkan permintaan GET ke endpoint files/{filename}. Respons mencakup properti file seperti ukuran dan waktu terakhir diubah.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files/<FILE_NAME_AND_EXTENSION>?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Mencantumkan file dalam sesi

Untuk mencantumkan file dalam direktori sesi /mnt/data, kirimkan permintaan GET ke titik akhir files.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

GET https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

Respons berisi daftar file dalam sesi.

Berikut ini adalah contoh jenis respons yang dapat Anda harapkan saat meminta konten sesi.

{
    "$id": "1",
    "value": [
        {
            "$id": "2",
            "properties": {
                "$id": "3",
                "filename": "test1.txt",
                "size": 16,
                "lastModifiedTime": "2024-05-02T07:21:07.9922617Z"
            }
        },
        {
            "$id": "4",
            "properties": {
                "$id": "5",
                "filename": "test2.txt",
                "size": 17,
                "lastModifiedTime": "2024-05-02T07:21:08.8802793Z"
            }
        }
    ]
}

Menghapus sesi

Gunakan API Hapus Sesi untuk mengakhiri sesi di kumpulan sesi penerjemah kode.

Setelah mengalokasikan sesi, Anda dapat memanggil API ini untuk menghentikannya secara manual kapan saja. Ini berguna ketika:

  • Anda perlu membersihkan sumber daya sebelum sesi mencapai "time-to-live"nya.
  • Kumpulan sesi Anda telah mencapai batas sesi bersamaan maksimumnya dan Anda perlu membebaskan kapasitas untuk sesi baru.
  • Sesi telah menyelesaikan pekerjaannya dan Anda ingin segera merilis sumber daya.

Referensi API

Permintaan

DELETE <POOL_MANAGEMENT_ENDPOINT>/session?api-version=2025-02-02-preview&identifier=<SessionIdentifier>

Parameter-parameternya

Parameter Type Required Deskripsi
api-version string Yes Versi API yang akan digunakan (misalnya, 2025-02-02-preview).
identifier string Yes Pengidentifikasi unik dari sesi yang akan dihentikan.

Examples

Permintaan

DELETE <POOL_MANAGEMENT_ENDPOINT>/session?api-version=2025-02-02-preview&identifier=testSessionIdentifier

Jawaban

HTTP/1.1 204 No Content

Mengambil informasi sesi

Anda bisa mengkueri kumpulan sesi untuk memeriksa status sesi, mendapatkan detail kedaluwarsa, dan mencantumkan semua sesi aktif. Kemampuan ini berguna untuk memantau kesehatan sesi, melacak penggunaan sumber daya, dan menerapkan alur kerja pembersihan kustom.

Dapatkan satu sesi

Untuk mengambil detail tentang sesi tertentu, gunakan API get session:

GET <POOL_MANAGEMENT_ENDPOINT>/session?identifier=<SessionIdentifier>&api-version=2025-02-02-preview

Titik getSession akhir mengembalikan metadata sesi termasuk pengidentifikasi sesi, waktu kedaluwarsa saat ini, dan tanda waktu pembuatan.

Skema respons SessionView

Ladang Type Required Deskripsi
identifier string Yes ID sesi yang Anda berikan
etag string Yes Pengidentifikasi versi opaque untuk sesi. Anda dapat menggunakan pengidentifikasi ini untuk deteksi perubahan.
expiresAt DateTime Yes Tanda waktu UTC ketika sesi akan dihentikan
createdAt DateTime No Tanda waktu pembuatan sesi
lastAccessedAt DateTime No Tanda waktu permintaan terakhir untuk sesi ini

Contoh permintaan dan respons

curl -X GET "https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool/session?identifier=user-123&api-version=2025-02-02-preview" \
  -H "Authorization: Bearer $TOKEN"

Respons keberhasilan (HTTP 200):

{
  "identifier": "user-123",
  "etag": "a1b2c3d4",
  "expiresAt": "2026-04-30T14:30:00Z",
  "createdAt": "2026-04-30T13:30:00Z",
  "lastAccessedAt": "2026-04-30T14:29:00Z"
}

Daftarkan semua sesi dalam kumpulan

Untuk mengambil daftar semua sesi dalam kumpulan sesi Anda, gunakan endpoint listSessions

GET <POOL_MANAGEMENT_ENDPOINT>/listSessions?skip=0&api-version=2025-02-02-preview
Authorization: Bearer <TOKEN>

Pagination

Titik akhir daftar mendukung penomoran halaman berbasis lewati. Secara default, setiap halaman mengembalikan hingga 300 sesi. skip Gunakan parameter kueri untuk menavigasi melalui hasil.

Parameter Deskripsi
skip Jumlah sesi yang akan dilewati dari awal (default: 0)
nextLink URL lengkap untuk halaman hasil berikutnya (disertakan sebagai respons saat ada lebih banyak hasil)

Skema respons untuk ApiCollectionEnvelope

Ladang Type Deskripsi
value SessionView[] Kumpulan objek sesi
nextLink string URL untuk halaman berikutnya (null jika tidak ada hasil lagi)

Contoh perulangan penomoran halaman

POOL_URL="https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool"
next_url="$POOL_URL/.management/listSessions?skip=0&api-version=2025-02-02-preview"

while [ -n "$next_url" ]; do
  response=$(curl -s "$next_url" \
    -H "Authorization: Bearer $TOKEN")

  echo "$response" | jq '.value[] | {identifier, expiresAt}'

  next_url=$(echo "$response" | jq -r '.nextLink // empty')
done

Contoh respons (HTTP 200):

{
  "value": [
    {
      "identifier": "user-123",
      "etag": "a1b2c3d4",
      "expiresAt": "2026-04-30T14:30:00Z",
      "createdAt": "2026-04-30T13:30:00Z",
      "lastAccessedAt": "2026-04-30T14:29:00Z"
    },
    {
      "identifier": "user-456",
      "etag": "e5f6a7b8",
      "expiresAt": "2026-04-30T14:30:00Z",
      "createdAt": "2026-04-30T13:30:00Z",
      "lastAccessedAt": "2026-04-30T14:29:00Z"
    }
  ],
  "nextLink": "https://eastasia.dynamicsessions.io/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myrg/sessionPools/mysessionpool/listSessions?skip=300"
}

Paket yang telah diinstal sebelumnya

Sesi penerjemah kode Python mencakup paket Python populer seperti NumPy, panda, dan scikit-learn.

Untuk menghasilkan daftar paket yang telah diinstal sebelumnya, panggil executions titik akhir dengan kode berikut.

Sebelum Anda mengirim permintaan, ganti placeholder dalam tanda <> dengan nilai khusus untuk permintaan Anda.

POST https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>/executions?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
    "properties": {
        "codeInputType": "inline",
        "executionType": "synchronous",
        "code": "import pkg_resources\n[(d.project_name, d.version) for d in pkg_resources.working_set]"
    }
}

Pencatatan

Output yang tersedia adalah hasil yang Anda kembalikan dari eksekusi kode, termasuk stdout dan stderr.

Jika Anda memerlukan pelacakan permintaan atau respons, rekam di aplikasi yang memanggil API manajemen kumpulan sesi (misalnya, catat ID permintaan, input, dan respons di batas aplikasi Anda).

Catatan

Sesi penerjemah kode tidak mengeluarkan log AppEnvSession ke Analitik Log.

Metode pengukuran

Metrik penggunaan dan eksekusi penerjemah kode dikembalikan sebagai header respons HTTP untuk API eksekusi kode. Metrik ini tidak ditulis ke Analitik Log.

Lihat metrik

  1. Panggil API eksekusi kode (/executions).
  2. Periksa header respons HTTP untuk metrik penggunaan dan eksekusi.

Untuk detail tentang API dan titik akhir eksekusi kode, lihat Menjalankan kode dalam sesi dan titik akhir API Manajemen.

Penagihan

Sesi penerjemah kode ditagih berdasarkan durasi setiap sesi. Untuk mengetahui informasi lebih lanjut, lihat Penagihan.

Langkah berikutnya

Menggunakan sesi penerjemah kode dengan LangChain

  • Terakhir diperbarui pada