Knowledge Base Referensi AI Provider

AI provider adalah layanan yang menerima request aplikasi, menjalankan model, lalu mengembalikan hasil. Memilih provider bukan hanya memilih model paling pintar. Anda juga memilih bentuk API, lokasi data, limit, cara billing, reliability, observability, dan jalur pemulihan ketika provider gagal.

Aturan utama: jangan mengaktifkan model baru di production hanya karena satu prompt di playground berhasil. Model harus melewati kontrak output, smoke test, timeout, retry, fallback, dan pencatatan usage aplikasi Anda.

1. Bedakan Model, Provider, dan Gateway

Nama model yang sama melalui dua provider belum tentu menerima parameter yang sama. Endpoint, nama field token, reasoning, structured output, usage response, dan error dapat berbeda. Karena itu aplikasi membutuhkan adapter per API surface, bukan sekadar mengganti string model.

2. Kapan Memilih Direct Provider atau Aggregator

Provider langsung

Pilih jalur langsung ketika Anda membutuhkan:

• akses tercepat ke fitur resmi model;
• kontrol kontrak dan support langsung dari vendor;
• region, privacy, atau enterprise agreement tertentu;
• observability dan billing langsung di satu vendor;
• parameter yang belum didukung aggregator.

Trade-off utamanya adalah Anda harus memelihara adapter, credential, limit, dan mekanisme fallback lintas provider.

Aggregator

Pilih aggregator ketika Anda membutuhkan:

• satu API untuk beberapa keluarga model;
• routing antar penyedia inference;
• katalog model dan metadata yang dapat ditemukan programmatically;
• fallback atau perbandingan model yang lebih cepat;
• billing gabungan.

Trade-off utamanya adalah ada lapisan tambahan. Periksa provider akhir, kebijakan data, parameter yang benar-benar diteruskan, latency routing, dan perbedaan harga.

Pola production yang sehat

Feature atau pipeline stage
        |
        v
AI gateway internal
  - schema validation
  - timeout budget
  - retry policy
  - usage and cost log
        |
        +--> Primary target
        +--> Fallback 1
        +--> Fallback 2

Fallback harus melewati adapter dan validator yang sama. Jangan memanggil fallback dari UI browser atau menyimpan credential provider di client.

3. Data Minimum untuk Setiap Provider

Simpan record provider dan model secara versioned. Minimum field yang diperlukan:

{
  "providerKey": "provider-slug",
  "connectionType": "direct_or_aggregator",
  "apiSurface": "responses_or_messages_or_generate_content",
  "baseUrl": "server-side configuration",
  "credentialEnv": "PROVIDER_API_KEY",
  "providerModelId": "exact-api-model-id",
  "lifecycle": "eval_or_active_or_deprecated",
  "capabilities": {
    "structuredOutput": true,
    "tools": true,
    "streaming": true,
    "reasoning": true
  },
  "limits": {
    "contextWindowTokens": null,
    "maxOutputTokens": null
  },
  "pricing": {
    "sourceUrl": "official-pricing-url",
    "verifiedAt": "YYYY-MM-DD",
    "pricingMode": "flat_or_tiered"
  },
  "conformance": {
    "status": "untested",
    "testedAt": null,
    "schemaVersion": "your-output-contract.v1"
  }
}

Jangan menganggap null berarti nol. Artinya informasi belum direkam atau belum diverifikasi.

4. Referensi Provider Utama

OpenAI direct

OpenAI menyediakan model melalui API resmi, dengan Responses API sebagai permukaan utama untuk banyak workflow baru. Verifikasi:

• exact model ID dan lifecycle;
• input modality dan output modality;
• reasoning effort yang didukung;
• batas output;
• structured output atau tool calling;
• rate limit organisasi dan project;
• field usage pada response.

Gunakan OPENAI_API_KEY hanya di server. Structured output membantu bentuk JSON, tetapi aplikasi tetap harus melakukan validasi semantic dan business rule.

Anthropic direct

Anthropic menggunakan Messages API dengan bentuk request dan response yang berbeda dari OpenAI. Perhatikan:

• system prompt berada pada field top-level yang sesuai API;
• max_tokens wajib pada request tertentu;
• output dapat berupa beberapa content block;
• stop reason dan usage harus dinormalisasi;
• model lifecycle dan tanggal retirement perlu dimonitor.

Gunakan exact model ID yang didukung dan uji parser terhadap text, tool call, refusal, serta error response.

Google Gemini direct

Gemini API menyediakan endpoint untuk menemukan model dan metadata capability. Nama model dapat berupa stable, preview, latest, atau experimental.

• Stable lebih cocok untuk production ketika tersedia.
• Preview dapat berubah dan mempunyai jadwal penghentian.
• Latest dapat menunjuk versi berbeda dari waktu ke waktu.
• Experimental tidak seharusnya dianggap stabil.

Structured output menggunakan subset JSON Schema. JSON yang valid secara syntax belum tentu benar secara semantic, jadi validator domain tetap wajib.

Alibaba Cloud Model Studio direct

Alibaba Model Studio menyediakan Qwen dan model lain melalui endpoint regional dan beberapa API surface. Verifikasi:

• workspace dan permission model;
• region endpoint;
• exact model code;
• dukungan structured output, tools, dan reasoning pada model tersebut;
• tier harga berdasarkan jumlah input token per request;
• harga cache hit dan cache creation bila digunakan;
• response dan error untuk 429.

Pada pricing bertingkat, jangan memakai satu harga per sejuta token untuk semua request. Tentukan tier dari total input token satu request, lalu hitung seluruh token request dengan harga tier tersebut sesuai dokumentasi provider.

OpenRouter

OpenRouter adalah aggregator dengan katalog model dan routing provider. Periksa:

• canonical model slug;
• supported parameters;
• provider order;
• allow_fallbacks;
• require_parameters untuk mencegah route yang tidak mendukung parameter wajib;
• kebijakan data collection dan zero-data-retention;
• metadata provider akhir dan attempt;
• usage serta billed cost.

Fallback dari OpenRouter dan fallback aplikasi adalah dua lapisan berbeda. Dokumentasikan siapa yang bertanggung jawab memilih provider akhir agar incident dapat ditelusuri.

5. Kontrak Output Sebelum Model Boleh Disimpan

Gunakan smoke test kecil tetapi representatif. Contoh kontrak:

{
  "type": "object",
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "language": { "type": "string", "enum": ["id", "en"] },
    "risks": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["summary", "language", "risks"],
  "additionalProperties": false
}

Prompt smoke test:

Baca ide berikut dan kembalikan hanya object yang sesuai schema.
Bahasa output harus mengikuti bahasa ide.

Ide: Aplikasi pencatatan pengeluaran keluarga dengan ringkasan bulanan.

Lulus hanya jika:

• status HTTP sukses;
• selesai sebelum timeout;
• output dapat diparse;
• schema lengkap tanpa field asing;
• bahasa benar;
• tidak ada code fence atau prose tambahan jika kontrak melarangnya;
• usage tersedia atau tercatat sebagai unsupported;
• log tidak menyimpan prompt sensitif;
• test diulang beberapa kali untuk melihat konsistensi.

6. Validasi Bertingkat

Model belum layak production bila baru melewati connectivity test.

7. Routing, Retry, dan Fallback

Retry hanya untuk error yang masuk akal dipulihkan, misalnya timeout sementara, koneksi, 429, atau sebagian 5xx. Jangan retry tanpa batas.

Request
  -> primary attempt
     -> success: validate and return
     -> retryable failure: bounded retry or fallback
     -> non-retryable failure: stop and report
  -> fallback attempt
     -> success: validate and return
     -> failure: persist safe diagnostic and support reference

Aturan minimum:

• total timeout budget, bukan timeout baru tanpa batas pada setiap target;
• exponential backoff dengan jitter untuk retry;
• hormati Retry-After bila tersedia;
• circuit breaker untuk provider yang terus gagal;
• idempotency pada job yang dapat ditagih atau menghasilkan side effect;
• jangan fallback bila schema atau policy target tidak kompatibel;
• log setiap attempt tanpa credential dan data sensitif.

8. Usage dan Perhitungan Cost

Utamakan data billing atau usage dari provider jika tersedia. Simpan setidaknya:

• provider dan model aktual;
• input, cached input, reasoning, dan output token jika tersedia;
• request ID provider;
• harga versi/tanggal yang dipakai untuk estimasi;
• reported cost dari provider atau calculated cost internal;
• mata uang dan kurs bila dikonversi;
• perbedaan antara estimasi dan invoice aktual.

Jika provider tidak mengembalikan cost, hitung dari usage dan tabel harga versioned. Untuk tiered pricing, tentukan tier per request. Jangan mencampur harga direct dengan harga aggregator atau harga model alias yang berbeda.

9. Security dan Data Governance

• Simpan API key di secret manager atau server environment.
• Pisahkan key development, staging, dan production.
• Batasi budget, rate, project, dan permission bila provider mendukung.
• Jangan log Authorization header atau raw secret.
• Redact personal data dari prompt log.
• Tentukan retention, training opt-out, region, dan data residency.
• Batasi siapa yang dapat mengubah routing production.
• Rekam siapa, kapan, dan mengapa model diaktifkan.
• Rotasi key setelah dugaan kebocoran.

Proxy server bukan pengganti authorization. Endpoint AI harus memeriksa user, entitlement, quota, dan scope sebelum memanggil provider.

10. Observability dan Incident Response

Dashboard operasional sebaiknya dapat menjawab:

• route apa yang dipanggil;
• model dan provider aktual;
• target utama atau fallback;
• latency per attempt;
• status HTTP dan normalized error code;
• input/output token;
• estimated atau reported cost;
• schema validation result;
• correlation ID atau Support ID;
• retryability dan langkah recovery.

Alert penting mencakup kenaikan 429, 5xx, timeout, invalid JSON, schema mismatch, cost spike, dan fallback rate. Fallback yang terlalu sering adalah incident yang tersembunyi, bukan tanda sistem selalu sehat.

11. Checklist Aktivasi Model Baru

• Provider record dan exact model ID sudah dibuat.
• Sumber resmi, tanggal verifikasi, lifecycle, region, dan harga tercatat.
• Adapter request/response sesuai API surface.
• Credential hanya server-side.
• Smoke test connectivity lulus.
• Structured output dan semantic assertions lulus beberapa kali.
• Timeout, 429, 5xx, retry, dan fallback disimulasikan.
• Usage dan cost dapat direkonsiliasi.
• Log aman dan correlation ID tersedia.
• Canary, alert, dan rollback tersedia.
• Aktivasi production menghasilkan audit event.

12. Freshness dan Governance

Review katalog minimal setiap 30 hari dan segera ketika ada model baru, perubahan harga, deprecation, perubahan privacy, atau kegagalan conformance. Simpan histori, jangan menimpa bukti lama. Model berstatus eval tidak boleh otomatis menjadi active hanya karena record-nya lengkap.

Database terstruktur yang ditampilkan setelah artikel ini adalah snapshot edukasi. AI Routing production harus tetap memakai konfigurasi, validation gate, dan approval operasional aplikasi.