Mengonfigurasi API perantara di berbagai kerangka kerja: dari SDK hingga Dify

Siapkan tiga nilai terlebih dahulu

Terlepas dari kerangka kerja yang Anda gunakan, pastikan Anda memiliki tiga hal ini terlebih dahulu; konfigurasi selanjutnya hanyalah mengisi formulir.

• Endpoint: https://api.llmzhongzhuan.com/v1. Pertahankan /v1 di akhir, tapi jangan tambahkan /chat/completions karena SDK akan menggabungkannya.
• Kunci API: Ditampilkan segera setelah Anda mendaftar dengan email dan kata sandi di halaman mendapatkan kunci. Setiap akun memiliki satu kunci yang dapat di-reset; kunci lama akan langsung tidak berlaku setelah di-reset.
• Nama model: hanya ada satu, uncensored. Anda dapat memverifikasinya sendiri dengan GET /v1/models.

Perhatikan batas: jendela konteks 100.000 token, max_tokens default 2048 (maks 32.000), dan 300 permintaan per menit per kunci. Angka ini sering dipakai di pengaturan parameter.

Penulisan Variabel Lingkungan

Mengunci kunci di kode adalah penyebab utama masalah. Gunakan variabel lingkungan yang diinjeksikan saat deployment. Contoh di bawah menggunakan API_KEY dan API_BASE untuk semua kerangka kerja.

复制# Linux / macOS：写进 ~/.zshrc 或 .env 加载脚本
export API_KEY="替换为你的密钥"
export API_BASE="https://api.llmzhongzhuan.com/v1"

# Windows PowerShell（仅当前会话）
$env:API_KEY = "替换为你的密钥"
$env:API_BASE = "https://api.llmzhongzhuan.com/v1"

Jika menggunakan file .env, tambahkan ke .gitignore. SDK Python membaca OPENAI_API_KEY dan OPENAI_BASE_URL. Anda bisa menggunakan nama ini atau meneruskannya secara eksplisit ke konstruktor agar tidak terpengaruh variabel lama.

SDK Python dan Node.js OpenAI

Python butuh paket openai v1+, Node butuh v4+. Bedanya hanya sintaks. Berikut contoh non-streaming Python yang mencetak usage untuk verifikasi biaya:

复制import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一条 20 字以内的发布公告标题。"}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

Contoh Node.js menggunakan output streaming, yang merupakan cara paling umum untuk efek ketikan di antarmuka depan. Saat permintaan streaming berakhir, server secara otomatis menambahkan fragmen yang menyertakan usage, sehingga tidak perlu parameter tambahan:

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.API_BASE ?? "https://api.llmzhongzhuan.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "列出三个命名服务端日志字段的好习惯。" }],
  stream: true,
  max_tokens: 300,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

Contoh Node menggunakan top-level await, butuh file .mjs atau pengaturan "type": "module" di package.json. Jika runtime tidak mendukung, bungkus dalam fungsi async.

LangChain: base_url untuk ChatOpenAI

LangChain tidak butuh adapter khusus. Gunakan ChatOpenAI dari paket langchain_openai dan arahkan base_url ke endpoint kami.

复制import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    temperature=0.7,
    max_tokens=500,
    timeout=60,
)

print(llm.invoke("把“服务已降级”改写成对用户友好的一句话。").content)

Tips: atur max_tokens dan timeout secara eksplisit. Untuk tool calls, kami mendukung format OpenAI; gunakan bind_tools LangChain. Untuk streaming, konsumsi blok di stream().

LlamaIndex: OpenAILike

Kelas OpenAI bawaan LlamaIndex memvalidasi nama model. Untuk model kustom, gunakan OpenAILike dari llama-index-llms-openai-like. Parameter alamatnya adalah api_base.

复制import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="uncensored",
    api_base=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    is_chat_model=True,
    context_window=100000,
    max_tokens=500,
)

print(llm.complete("用一句话解释什么是幂等请求。"))

is_chat_model=True penting agar LlamaIndex menggunakan endpoint chat. Set context_window ke 100.000 agar dokumen tidak terpotong pada batas token default.

Dify: Pemasok OpenAI-API-compatible

Platform visual seperti Dify tidak menggunakan kode, melainkan dikonfigurasi melalui formulir. Teks antarmuka mungkin sedikit berbeda antar versi, tetapi langkah-langkahnya pada dasarnya sama:

1. Masuk ke "Pengaturan", temukan halaman "Pemasok Model", pilih "OpenAI-API-compatible" dari daftar, lalu klik "Tambah Model".
2. Pilih tipe model "LLM" dan isi nama model dengan uncensored.
3. Isi API Key dengan kunci Anda, dan API endpoint URL dengan https://api.llmzhongzhuan.com/v1.
4. Isi panjang konteks model dengan 100000 dan batas token maksimum dengan 32000.
5. Jika Anda ingin menggunakan pemanggilan fungsi dalam alur kerja, aktifkan opsi dukungan pemanggilan fungsi; biarkan output streaming tetap aktif.
6. Setelah disimpan, buat aplikasi obrolan sederhana, pilih model yang baru ditambahkan, dan kirim pesan untuk memverifikasi bahwa responsnya normal.

Platform terkadang mengirimkan permintaan probe saat penyimpanan. Jika langkah ini gagal, biasanya karena alamat memiliki path berlebih atau kunci memiliki spasi di awal/akhir. Jika Dify Anda di-deploy dalam kontainer, pastikan kontainer tersebut dapat mengakses domain eksternal.

Parameter dan Penulisan Deployment yang Perlu Dicek Sebelum Peluncuran

Kemampuan kerangka kerja untuk berjalan hanyalah langkah pertama. Parameter berikut sebaiknya diperiksa satu per satu sebelum peluncuran karena mereka menentukan biaya dan tingkat kegagalan.

• max_tokens: Default 2048; tingkatkan secara eksplisit jika memerlukan output teks panjang, dengan batas maksimum 32,000. Perhatikan bahwa jumlah input dan output tidak boleh melebihi 100,000, jika tidak Anda akan menerima error 400.
• timeout: Permintaan dengan output panjang membutuhkan waktu lebih lama. Untuk skenario streaming, disarankan mengatur read timeout ke atas 60 detik; untuk non-streaming, estimasikan berdasarkan output terpanjang.
• temperature / top_p / stop: Parameter sampling standar ini diteruskan langsung; nilai yang diatur di kerangka kerja akan langsung berlaku tanpa perlu sakelar tambahan.
• Permintaan paralel: Setiap kunci API membatasi 300 permintaan per menit. Saat beberapa instance berbagi kunci yang sama, batas laju dihitung secara gabungan, jadi jangan merencanakan setiap instance secara terpisah hingga 300.
• Retry: Retry bawaan kerangka kerja biasanya hanya untuk error jaringan. Untuk 429 dan 503, tambahkan backoff secara manual (lihat bagian stabilitas).

Saat mendeploy ke kontainer, prinsipnya tetap sama: "tidak ada kunci dalam image"; nilai-nilai tersebut disuntikkan oleh alat orkestrasi saat startup. Berikut adalah penulisan minimum di compose:

复制# docker-compose.yml 片段
services:
  app:
    image: your-app:latest
    environment:
      API_BASE: https://api.llmzhongzhuan.com/v1
      API_KEY: ${API_KEY}   # 从宿主机环境或 .env 读取，不写进镜像

Di Kubernetes, ganti dengan referensi Secret dengan prinsip yang sama. Disarankan juga menyiapkan akun atau kunci yang berbeda untuk lingkungan yang berbeda, misalnya satu set untuk pengembangan, pra-produksi, dan produksi. Dengan demikian, jika kunci atau saldo salah satu lingkungan habis atau bocor, lingkungan produksi tidak akan terpengaruh. Karena setiap akun hanya memiliki satu kunci, sebaiknya gunakan beberapa akun untuk beberapa lingkungan dan lakukan top up saldo yang sesuai secara terpisah.

Terakhir, tentang log. Banyak kerangka kerja mencetak header permintaan lengkap saat mode debug, yang mencakup Authorization. Pastikan untuk menonaktifkan output debug ini di lingkungan produksi, atau lakukan masking kunci di filter log. Mencatat bidang usage adalah praktik baik karena membantu Anda mencocokkan tagihan dan mendeteksi dini jika prompt untuk fitur tertentu tiba-tiba menjadi lebih panjang.

Urutan Pemecahan Masalah Saat Error

90% masalah pada tahap integrasi terkonsentrasi pada beberapa area berikut. Periksa sesuai urutan di bawah ini untuk hasil tercepat:

1. 401: Kunci API kosong, mengandung spasi saat disalin, atau Anda masih menggunakan kunci lama setelah direset.
2. 404: Alamat ditulis sebagai jalur root tanpa /v1, atau menambahkan /chat/completions secara berlebihan.
3. 402: Kode kesalahan no_credit menunjukkan saldo habis atau kredit uji coba gratis telah kedaluwarsa, sehingga Anda perlu mengisi saldo prabayar.
4. 400: Penyebab umumnya adalah input yang menggabungkan max_tokens melebihi 100,000, atau badan permintaan melebihi 8 MB.
5. 429 / 503: Yang pertama adalah batas laju 300 permintaan per menit, yang kedua adalah upstream_busy. Tunggu beberapa detik lalu coba lagi; lihat praktik stabilitas untuk detailnya.

Ada juga masalah lingkungan jaringan yang sering terlewatkan. Jaringan perusahaan, perangkat lunak proxy, atau aturan grup keamanan dapat menyebabkan resolusi domain berhasil tetapi koneksi HTTPS gagal, yang ditandai dengan waktu tunggu lama lalu waktu tunggu habis, bukan kode kesalahan yang jelas. Jika mengalami ini, gunakan curl untuk mengakses /v1/models dari mesin yang sama; jika berhasil, masalah ada di lapisan aplikasi; jika gagal, periksa proxy dan firewall. Dokumentasikan proses pemecahan masalah ini dalam dokumen tim agar rekan baru tidak perlu melalui proses yang sama saat terhubung.

Ketika ketiga nilai benar namun masih gagal, gunakan curl untuk melakukan permintaan langsung guna mengesampingkan masalah dari kerangka kerja. Jika ingin memahami apa yang sebenarnya dilakukan oleh perantara, baca kembali prinsip perantara.