Portkey: Satu Gateway AI buat Ngatur Semua LLM dari Banyak Provider

Temen-temen, kalau kamu udah pernah bikin aplikasi yang manggil LLM, entah itu OpenAI, Anthropic, Google, atau model open source di Together, pasti kamu ngerasain satu hal yang sama: makin lama kodenya makin berantakan. Ada key yang kesebar di mana-mana, ada retry yang kamu tulis manual tiap kali API-nya timeout, ada fallback yang kamu bikin pakai try-except panjang, dan pas produksi kamu bingung kenapa biayanya membengkak karena nggak ada yang ngelacak berapa token yang kepake tiap hari. Aku sendiri udah ngalamin fase itu dan jujur bikin capek.

Nah, di tutorial kali ini aku mau ngenalin ke kamu satu tool yang menurutku wajib kamu tau kalau kamu serius bangun aplikasi berbasis LLM, namanya Portkey. Portkey ini adalah AI gateway sekaligus observability layer buat aplikasi LLM. Konsep intinya simpel banget: kamu taruh satu gateway di depan semua provider, terus semua request LLM kamu lewat gateway itu. Dari situ kamu dapet banyak fitur gratisan yang tadinya harus kamu bikin sendiri, kayak retry otomatis, fallback, load balancing, caching, logging, tracing, sampai guardrails.

Di artikel ini aku bakal ajak kamu jalan pelan-pelan dari nol. Kita mulai dari konsep, install, basic usage pakai SDK dan cara OpenAI-compatible, terus lanjut ke fitur-fitur advanced kayak virtual keys, retry, fallback, load balancing, semantic caching, observability, dan guardrails. Semua ada contoh kode Python yang bisa langsung kamu jalanin. Yuk kita mulai.

Introduction: Kenapa Butuh AI Gateway

Sebelum masuk ke kode, aku mau kamu paham dulu masalah yang mau diselesain sama Portkey. Bayangin kamu punya aplikasi chatbot. Awalnya kamu cuma pakai OpenAI. Kodenya bersih, tinggal panggil client.chat.completions.create. Tapi begitu aplikasi kamu makin serius, kebutuhan baru mulai muncul satu-satu.

Kebutuhan pertama biasanya soal keandalan. API LLM itu nggak selalu jalan mulus. Kadang timeout, kadang kena rate limit, kadang error 500 dari sisi provider. Kalau request-nya gagal, kamu nggak mau langsung nyerah kan. Kamu mau retry dulu beberapa kali. Kalau OpenAI lagi down parah, kamu mau otomatis pindah ke Anthropic biar aplikasi tetep jalan. Ini yang namanya fallback.

Kebutuhan kedua soal biaya dan visibilitas. Kamu perlu tau berapa banyak request yang masuk, berapa token yang kepake, berapa biayanya, model mana yang paling sering dipanggil, dan request mana yang lambat atau error. Tanpa observability, kamu buta total. Pas tagihan datang kamu cuma bisa kaget.

Kebutuhan ketiga soal efisiensi. Banyak request yang sebenernya mirip-mirip atau bahkan sama persis. Kalau tiap kali harus mukul LLM beneran, itu buang-buang duit dan bikin lambat. Di sinilah caching main peran, apalagi semantic caching yang bisa ngenalin pertanyaan yang mirip walau kata-katanya beda.

Kebutuhan keempat soal keamanan dan kualitas output. Kamu nggak mau model kamu bocorin data sensitif, atau ngeluarin output yang nggak sesuai format. Guardrails ngebantu kamu ngevalidasi input dan output secara otomatis.

Portkey ngejawab semua kebutuhan itu dalam satu tempat. Jadi alih-alih kamu nulis semua logika itu manual di tiap aplikasi, kamu cukup arahin request kamu lewat gateway Portkey dan atur semuanya lewat konfigurasi. Gateway-nya sendiri open source dan bisa kamu self-host, tapi Portkey juga punya versi hosted yang gratis buat mulai. Menariknya lagi, Portkey punya interface yang OpenAI-compatible, jadi kalau kode kamu udah pakai SDK OpenAI, migrasi ke Portkey itu cuma ganti base URL sama header doang. Nyaris nggak ada perubahan besar.

Instalasi

Oke sekarang kita mulai praktik. Pertama, install SDK Portkey buat Python. Buka terminal kamu terus jalanin perintah ini.

pip install portkey-ai

Kalau kamu mau pakai cara OpenAI-compatible, kamu juga bisa install SDK OpenAI karena Portkey bisa nempel di atasnya.

pip install openai portkey-ai

Setelah itu kamu butuh API key dari Portkey. Kamu bisa daftar gratis di dashboard Portkey, terus generate API key di menu settings. API key ini nanti dipakai buat autentikasi ke gateway Portkey. Aku saranin simpen key-nya di environment variable biar nggak ketulis di kode dan nggak kebawa ke git.

export PORTKEYAPIKEY="pk-xxxxxxxxxxxxxxxxx"
export OPENAIAPIKEY="sk-xxxxxxxxxxxxxxxxx"

Buat provider LLM kayak OpenAI atau Anthropic, kamu punya dua pilihan cara ngasih key-nya. Cara pertama, kamu kirim langsung key provider-nya lewat header tiap request. Cara kedua yang lebih rapi, kamu bikin virtual key di dashboard Portkey. Nanti aku bahas lebih detail soal virtual key di bagian advanced. Buat sekarang kita mulai dari cara paling dasar dulu.

Sekadar buat mastiin instalasi kamu jalan, coba kode kecil ini buat ngecek versi.

import portkeyai

print("Portkey version:", portkeyai.version)

Kalau versinya kecetak tanpa error, berarti kamu udah siap lanjut. Gampang banget kan.

Basic Usage

Sekarang kita bikin panggilan LLM pertama lewat Portkey. Ada dua gaya yang bisa kamu pakai. Gaya pertama pakai SDK Portkey langsung, gaya kedua pakai SDK OpenAI yang diarahin ke gateway Portkey. Aku bakal tunjukin dua-duanya biar kamu bebas milih.

Pakai SDK Portkey Langsung

Ini cara paling native. Kamu bikin objek Portkey, kasih API key Portkey kamu, terus tentuin provider dan key provider-nya. Struktur pemanggilannya mirip banget sama OpenAI jadi kamu bakal langsung familiar.

import os
from portkeyai import Portkey


client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],
    provider="openai",
    Authorization=f"Bearer {os.environ['OPENAIAPIKEY']}",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Kamu asisten yang ramah dan ringkas."},
        {"role": "user", "content": "Jelasin apa itu AI gateway dalam dua kalimat."},
    ],
)

print(response.choices[0].message.content)

Perhatiin, isi request-nya sama persis kayak kamu manggil OpenAI biasa. Bedanya cuma di objek client-nya. Semua request yang lewat sini otomatis kecatat di dashboard Portkey, jadi tanpa nambah kode apapun kamu udah dapet logging gratis.

Pakai SDK OpenAI dengan Gateway Portkey

Kalau kamu udah punya codebase yang penuh pakai SDK OpenAI dan males ngubah banyak, kamu bisa tetep pakai SDK OpenAI tapi arahin base URL-nya ke gateway Portkey. Portkey nyediain helper buat bikin base URL dan header yang bener.

import os
from openai import OpenAI
from portkeyai import PORTKEYGATEWAYURL, createHeaders


client = OpenAI(
    apikey=os.environ["OPENAIAPIKEY"],
    baseurl=PORTKEYGATEWAYURL,

    defaultheaders=createHeaders(
        apikey=os.environ["PORTKEYAPIKEY"],

        provider="openai",
    ),
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Sebutin tiga manfaat pakai AI gateway."},
    ],
)

print(response.choices[0].message.content)

Lihat kan, sisa kodenya identik sama OpenAI biasa. Kamu cuma nambah baseurl sama defaultheaders. Inilah kenapa migrasi ke Portkey itu nyaris nggak nyakitin. Buat tim yang udah gede codebase-nya, ini penyelamat.

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tulis pantun singkat soal AI."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

import os
from portkeyai import Portkey

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],

    virtualkey="openai-prod-xxxx",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Halo, kamu jalan lewat virtual key?"}],
)

print(response.choices[0].message.content)

Gampang kan. Kamu nggak perlu lagi nyebut Authorization atau key provider di kode. Semua diurus di sisi Portkey lewat virtual key tadi.

Config: Otak dari Semua Fitur Advanced

Sebelum masuk ke retry, fallback, dan load balancing, kamu perlu kenalan sama konsep Config. Config adalah objek konfigurasi berbentuk JSON yang ngatur gimana gateway memperlakukan request kamu. Di dalam config kamu bisa nentuin strategi retry, fallback, load balancing, caching, sampai guardrails. Kamu bisa bikin config langsung di kode sebagai dict, atau kamu simpen di dashboard dan cukup nyebut config ID-nya.

Aku bakal banyak pakai config di contoh-contoh berikutnya, jadi biasain sama bentuknya. Intinya config itu kamu kirim lewat parameter config pas bikin client.

Automatic Retries

Retry adalah fitur paling gampang tapi paling ngefek. Kalau request kamu gagal karena error yang sifatnya sementara, kayak rate limit atau server error, gateway bakal otomatis nyoba lagi. Kamu tinggal atur berapa kali dan buat status code apa aja.

import os
from portkeyai import Portkey


config = {
    "retry": {
        "attempts": 3,
        "onstatuscodes": [429, 500, 502, 503, 504],

    },
    "virtualkey": "openai-prod-xxxx",
}

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],

    config=config,
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Coba retry otomatis."}],
)

print(response.choices[0].message.content)

import os
from portkeyai import Portkey

config = {
    "strategy": {"mode": "fallback"},
    "targets": [
        {
            "virtualkey": "openai-prod-xxxx",

            "overrideparams": {"model": "gpt-4o-mini"},
        },
        {
            "virtualkey": "anthropic-prod-xxxx",

            "overrideparams": {"model": "claude-3-5-sonnet-latest"},
        },
    ],
}

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],

    config=config,
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Kalau OpenAI down, kamu pindah ke Anthropic ya."}],
)

print(response.choices[0].message.content)

Perhatiin di sini aku nggak nulis model di pemanggilan, karena tiap target udah punya overrideparams sendiri. Jadi kalau OpenAI gagal, gateway langsung nyoba Anthropic pakai model Claude. Buat aplikasi produksi yang nggak boleh mati, pola ini penting banget. Aplikasi kamu jadi tahan banting walau satu provider bermasalah.

Load Balancing

Kadang kamu punya beberapa key atau beberapa provider yang setara, dan kamu mau bagi beban request ke mereka. Alasannya bisa buat naikin throughput, ngakalin rate limit per key, atau nyebar biaya. Load balancing di Portkey ngebolehin kamu ngasih bobot ke tiap target.

import os
from portkeyai import Portkey


config = {
    "strategy": {"mode": "loadbalance"},
    "targets": [
        {
            "virtualkey": "openai-key-a",
            "weight": 0.7,
            "overrideparams": {"model": "gpt-4o-mini"},

        },
        {
            "virtualkey": "openai-key-b",
            "weight": 0.3,
            "overrideparams": {"model": "gpt-4o-mini"},

        },
    ],
}

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],
    config=config,
)

for i in range(5):
    response = client.chat.completions.create(
        messages=[{"role": "user", "content": f"Request nomor {i}"}],
    )
    print(response.choices[0].message.content)

Dengan bobot 0.7 dan 0.3, kira-kira 70 persen request bakal ke key A dan 30 persen ke key B. Kamu bisa gabung load balancing sama fallback juga, jadi tiap target di load balance bisa punya fallback sendiri. Fleksibel banget buat setup produksi yang serius.

Semantic Caching

Caching adalah cara cepet buat hemat biaya dan waktu. Portkey punya dua mode caching. Yang pertama simple cache, yang nyimpen jawaban kalau request-nya sama persis. Yang kedua semantic cache, yang lebih pinter karena dia ngenalin pertanyaan yang maknanya mirip walau kata-katanya beda. Misalnya "apa ibukota Indonesia" dan "sebutkan ibukota negara Indonesia" itu beda teks tapi maksudnya sama. Semantic cache bisa ngasih jawaban dari cache buat dua-duanya.

import os
from portkeyai import Portkey


config = {
    "cache": {
        "mode": "semantic",
        "maxage": 3600,
    },
    "virtualkey": "openai-prod-xxxx",

}

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],
    config=config,
)

Panggilan pertama mukul LLM beneran
r1 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Apa ibukota Indonesia?"}],
)
print("Pertama:", r1.choices[0].message.content)

Panggilan kedua maknanya mirip, harusnya dilayani dari cache
r2 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Sebutkan ibukota negara Indonesia dong."}],
)
print("Kedua:", r2.choices[0].message.content)

Parameter maxage nentuin berapa lama cache dianggap valid dalam detik. Di contoh ini satu jam. Buat aplikasi FAQ atau customer support yang banyak pertanyaan berulang, semantic caching bisa motong biaya kamu drastis. Aku pernah lihat kasus di mana lebih dari separuh request bisa dilayani dari cache. Lumayan banget buat kantong.

import os
from portkeyai import Portkey

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],

    virtualkey="openai-prod-xxxx",
    traceid="percakapan-abc-123",

    metadata={
        "userid": "user42",

        "fitur": "chatbot-support",
        "environment": "production",
    },
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Gimana cara reset password?"}],
)

print(response.choices[0].message.content)

import os
from portkeyai import Portkey

config = {
    "virtualkey": "openai-prod-xxxx",

    "inputguardrails": ["guardrail-cek-pii-xxxx"],
    "outputguardrails": ["guardrail-valid-json-xxxx"],

}

client = Portkey(
    apikey=os.environ["PORTKEYAPIKEY"],
    config=config,
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Balas hanya dalam JSON valid dengan kunci jawaban."},
        {"role": "user", "content": "Apa ibukota Jepang?"},
    ],
)

print(response.choices[0].message.content)

Di contoh ini aku pasang guardrail input buat ngecek PII sebelum request dikirim, dan guardrail output buat mastiin balasan itu JSON valid. Kalau output-nya bukan JSON, kamu bisa atur biar Portkey nge-retry atau nolak. Guardrails ini penting banget kalau aplikasi kamu masuk ranah yang sensitif kayak kesehatan atau keuangan, di mana output yang ngawur bisa berabe.

Best Practices

Setelah kamu tau semua fiturnya, aku mau bagi beberapa saran biar pemakaian Portkey kamu makin rapi dan aman.

Pertama, selalu pakai virtual key buat produksi dan jangan pernah hardcode key provider di kode. Simpen key asli di brankas Portkey, dan simpen API key Portkey kamu di environment variable atau secret manager. Ini ngurangin risiko key bocor dan bikin rotasi key jadi gampang.

Kedua, pisahin config buat tiap lingkungan. Bikin config development yang mungkin nggak pakai fallback mahal, dan config production yang lengkap dengan retry, fallback, dan guardrails. Dengan nyimpen config di dashboard dan nyebut lewat ID, kamu bisa ganti perilaku gateway tanpa deploy ulang aplikasi.

Ketiga, mulai dari yang sederhana lalu tambah sesuai kebutuhan. Jangan langsung nyalain semua fitur di hari pertama. Mulai dari logging dulu biar kamu paham pola trafik kamu. Habis itu tambah retry, terus fallback, terus caching kalau kamu lihat banyak request berulang. Nyalain fitur berdasarkan data yang kamu lihat di dashboard, bukan cuma karena fiturnya ada.

Keempat, hati-hati sama semantic caching di kasus yang butuh jawaban selalu segar. Semantic cache hebat buat pertanyaan yang jawabannya stabil, tapi jangan kamu pakai buat request yang hasilnya harus selalu baru atau bergantung waktu, kayak harga real time atau data yang sering berubah. Set max_age yang masuk akal sesuai konteks.

Kelima, manfaatin metadata dan trace ID dari awal. Kelihatannya sepele, tapi pas aplikasi kamu udah gede dan kamu perlu debug atau bikin laporan biaya per fitur, data ini bakal jadi penyelamat. Biasain nempelin user ID, nama fitur, dan environment di tiap request.

Keenam, kombinasiin fallback sama guardrails buat keandalan output. Misalnya kalau output guardrail gagal validasi JSON, kamu bisa atur fallback ke model yang lebih pinter. Jadi keandalan kamu bukan cuma soal provider hidup atau mati, tapi juga soal kualitas output yang konsisten.

Ketujuh, pantau biaya secara rutin lewat dashboard. Salah satu keuntungan terbesar Portkey adalah visibilitas biaya. Sisihin waktu tiap minggu buat lihat model mana yang paling boros dan apakah kamu bisa turunin ke model yang lebih murah tanpa ngorbanin kualitas. Banyak tim yang kaget ternyata mereka bisa hemat besar cuma dengan mindahin sebagian trafik ke model yang lebih kecil.

Conclusion

Oke temen-temen, kita udah jalan jauh dari sekadar konsep sampai contoh kode yang lengkap. Aku harap sekarang kamu punya gambaran jelas kenapa AI gateway kayak Portkey itu bukan cuma tambahan yang keren, tapi beneran ngebantu kamu bangun aplikasi LLM yang andal, hemat, dan gampang dipantau.

Intinya begini. Portkey naruh satu gateway di depan semua provider LLM kamu. Dari titik itu kamu dapet retry otomatis biar tahan error sementara, fallback biar aplikasi tetep hidup walau satu provider mati, load balancing biar beban kebagi rata, semantic caching biar hemat biaya dan cepet, observability biar kamu nggak buta soal trafik dan biaya, plus guardrails biar output kamu aman dan sesuai aturan. Dan yang paling enak, karena interface-nya OpenAI-compatible, migrasinya nyaris nggak nyakitin.

Saranku, jangan cuma baca. Coba langsung. Mulai dari daftar akun Portkey, install pip install portkey-ai, terus jalanin contoh basic usage di atas. Rasain sendiri gimana enaknya semua request kamu langsung kecatat di dashboard tanpa nulis kode logging. Habis itu pelan-pelan nyalain fitur lain sesuai kebutuhan aplikasi kamu. Kalau kamu bangun aplikasi LLM yang serius mau naik ke produksi, punya gateway kayak gini bakal ngebedain antara aplikasi yang rapuh dan aplikasi yang tahan banting.

Sekian dulu dari aku. Selamat ngoprek Portkey, dan semoga aplikasi LLM kamu makin mantap. Kalau ada pertanyaan, aku selalu senang bantu. Sampai ketemu di tutorial berikutnya ya temen-temen.