ADVERTISEMENT

Artikel ini memberikan panduan langkah‑demi‑langkah untuk memanfaatkan model openai/gpt-oss-120b:free melalui layanan OpenRouter.ai dengan bahasa pemrograman Python. Baik Anda pemula yang baru mengenal API LLM maupun pengembang berpengalaman, materi ini dirancang agar mudah diikuti dan langsung dapat dipraktekkan.

Pendahuluan

OpenRouter.ai adalah platform agregator yang menyatukan berbagai Large Language Model (LLM) dari penyedia berbeda dalam satu endpoint API. Salah satu model yang disediakan secara gratis adalah openai/gpt-oss-120b:free, sebuah varian open‑source dengan 120 miliar parameter yang cocok untuk tugas‑tugas generasi teks, summarization, atau analisis bahasa.

Menggunakan model ini lewat Python memberi Anda fleksibilitas untuk mengintegrasikannya ke dalam aplikasi web, chatbot, atau pipeline data science tanpa harus mengelola infrastruktur server sendiri. Pada tutorial ini kita akan membahas persiapan, implementasi kode, contoh penggunaan nyata, serta praktik terbaik dan cara mengatasi masalah umum.


Persiapan

Sebelum menulis kode, pastikan semua prasyarat berikut sudah dipenuhi.

  1. Akun OpenRouter.ai – Daftar di https://openrouter.ai dan verifikasi email. Setelah login, Anda dapat membuat API Key pada halaman Dashboard → API Keys.
  2. Python 3.8+ – Pastikan interpreter Python terpasang. Disarankan menggunakan virtual environment (venv) atau Conda untuk mengisolasi dependensi.
  3. Koneksi Internet Stabil – Model berada di cloud, sehingga permintaan API memerlukan jaringan yang dapat diandalkan.
  4. Editor Kode – VS Code, PyCharm, atau editor favorit lainnya.

Instalasi Dependensi

OpenRouter belum menyediakan paket resmi Python, sehingga kita akan menggunakan library requests untuk berkomunikasi dengan API HTTP.

# Buat virtual environment (opsional)
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Instal library yang dibutuhkan
pip install --upgrade pip
pip install requests tqdm

Catatan: tqdm hanya diperlukan bila Anda ingin menampilkan progress bar pada batch request.


Langkah‑Langkah

Berikut urutan aksi yang harus dilakukan untuk mengirim prompt ke model openai/gpt-oss-120b:free.

1. Membuat API Key di OpenRouter

  1. Masuk ke dashboard OpenRouter.
  2. Pilih API KeysCreate New Key.
  3. Beri nama (misalnya gpt‑oss‑120b‑key) dan salin nilai kunci yang muncul. Simpan di tempat yang aman, misalnya file .env.

2. Menyiapkan File Konfigurasi

Simpan API key dalam file .env agar tidak tertulis langsung di kode.

# .env
OPENROUTER_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gunakan library python-dotenv untuk memuatnya (opsional).

pip install python-dotenv

3. Membuat Fungsi Wrapper untuk API

Berikut contoh fungsi Python yang mengirim permintaan ke endpoint OpenRouter dan mengembalikan respons teks.

import os
import json
import requests
from dotenv import load_dotenv

load_dotenv()  # Muat .env

API_URL = "https://openrouter.ai/api/v1/chat/completions"
API_KEY = os.getenv("OPENROUTER_API_KEY")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "HTTP-Referer": "https://yourapp.example.com",   # Optional, untuk tracking
    "X-Title": "OpenRouter Python Demo"               # Optional, untuk monitoring
}

def chat_gpt_oss(prompt: str, temperature: float = 0.7, max_tokens: int = 512) -> str:
    """Kirim prompt ke model openai/gpt-oss-120b:free dan kembalikan teks hasil.
    
    Args:
        prompt (str): Teks yang ingin diproses.
        temperature (float): Nilai randomness, 0.0‑1.0.
        max_tokens (int): Batas token output.
    
    Returns:
        str: Jawaban model.
    """
    payload = {
        "model": "openai/gpt-oss-120b:free",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": prompt}
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": False
    }

    response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=30)
    if response.status_code != 200:
        raise RuntimeError(f"API error {response.status_code}: {response.text}")
    data = response.json()
    # Struktur respons: {"choices": [{"message": {"content": "..."}}]}
    return data["choices"][0]["message"]["content"].strip()

# Contoh pemanggilan fungsi
if __name__ == "__main__":
    contoh_prompt = "Jelaskan perbedaan antara supervised learning dan unsupervised learning dalam 150 kata."
    jawaban = chat_gpt_oss(contoh_prompt)
    print(jawaban)

4. Menjalankan Skrip

python gpt_oss_demo.py

Jika semuanya berjalan baik, Anda akan melihat output berupa penjelasan singkat tentang supervised vs unsupervised learning.


Contoh Penggunaan

Berikut beberapa skenario nyata yang dapat Anda adaptasi.

A. Membuat Chatbot Sederhana

import time

while True:
    user_input = input("Anda: ")
    if user_input.lower() in {"exit", "quit"}:
        print("Bot: Sampai jumpa!")
        break
    reply = chat_gpt_oss(user_input, temperature=0.6)
    print(f"Bot: {reply}\n")
    time.sleep(0.5)  # Hindari spam request

B. Batch Summarization Dokumen

Misalkan Anda memiliki daftar artikel yang ingin diringkas.

from tqdm import tqdm

articles = [
    "... teks artikel 1 ...",
    "... teks artikel 2 ...",
    # dst.
]

summaries = []
for text in tqdm(articles, desc="Summarizing"):
    prompt = f"Ringkas teks berikut dalam 100 kata: \n\n{text}"
    summary = chat_gpt_oss(prompt, temperature=0.3, max_tokens=150)
    summaries.append(summary)

# Simpan hasil ke file
with open("summaries.txt", "w", encoding="utf-8") as f:
    for i, s in enumerate(summaries, 1):
        f.write(f"=== Artikel {i} ===\n{s}\n\n")

C. Integrasi dengan FastAPI

Jika Anda ingin mengekspor fungsi sebagai layanan web:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class PromptRequest(BaseModel):
    prompt: str
    temperature: float = 0.7
    max_tokens: int = 512

@app.post("/generate")
async def generate(req: PromptRequest):
    try:
        result = chat_gpt_oss(req.prompt, req.temperature, req.max_tokens)
        return {"output": result}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Deploy dengan uvicorn main:app --reload dan akses endpoint /generate menggunakan curl atau Postman.


Best Practice

PraktikPenjelasan
Gunakan system promptMenetapkan peran atau gaya bahasa di awal membantu menjaga konsistensi output.
Batasi max_tokensMengurangi biaya dan menghindari respons yang terlalu panjang.
Atur temperature sesuai kebutuhanNilai rendah (0.2‑0.4) untuk jawaban faktual; nilai tinggi (0.8‑1.0) untuk kreativitas.
Implementasikan Retry LogicKarena layanan berbasis cloud, kegagalan jaringan dapat terjadi. Gunakan exponential backoff.
Pantau penggunaan tokenOpenRouter menyediakan metrik token; gunakan untuk mengontrol biaya.
Cache hasil yang sering dipakaiJika prompt serupa dipanggil berulang, simpan hasil di Redis atau memori lokal.
Jangan hard‑code API keySelalu gunakan variabel lingkungan atau secret manager.

Contoh retry sederhana:

import time

def safe_chat(prompt, retries=3, backoff=2):
    for attempt in range(1, retries + 1):
        try:
            return chat_gpt_oss(prompt)
        except Exception as err:
            if attempt == retries:
                raise
            time.sleep(backoff ** attempt)

Troubleshooting

MasalahPenyebab UmumSolusi
401 UnauthorizedAPI key tidak valid atau belum dimasukkan.Pastikan OPENROUTER_API_KEY benar, tidak ada spasi, dan telah di‑load dari .env.
429 Too Many RequestsRate limit terlewati (biasanya 60‑120 req/menit untuk plan gratis).Tambahkan jeda (time.sleep) atau gunakan algoritma token bucket untuk mengatur laju.
500 Internal Server ErrorGangguan sisi server OpenRouter.Coba lagi setelah beberapa menit; periksa status halaman status OpenRouter.
TimeoutKoneksi lambat atau server tidak merespon dalam batas waktu.Tingkatkan timeout pada requests.post (mis. timeout=60).
JSONDecodeErrorRespons bukan JSON (mis. HTML error page).Cetak response.text untuk melihat isi sebenarnya, kemudian perbaiki request.
Output terpotongmax_tokens terlalu kecil atau model menghentikan output karena token limit.Naikkan nilai max_tokens atau periksa apakah prompt terlalu panjang.

Langkah Debug Umum

  1. Print Header & Payload – Sebelum mengirim request, cetak HEADERS dan payload untuk memastikan format JSON valid.
  2. Cek Log Response – Simpan response.status_code dan response.text ke file log.
  3. Gunakan curl – Verifikasi bahwa endpoint dapat diakses di luar kode Python.
  4. Periksa Quota – Di dashboard OpenRouter, lihat sisa kuota token untuk model gratis.

Dengan mengikuti panduan ini, Anda sudah dapat memanfaatkan model openai/gpt-oss-120b:free secara efektif melalui OpenRouter.ai menggunakan Python. Selamat bereksperimen dan mengintegrasikan kemampuan LLM ke dalam proyek Anda!

ADVERTISEMENT