Memulai dengan curl
Permintaan mode JSON terkecil yang berfungsi terlihat seperti ini. Ini menggunakan base URL https://api.uncensoredllmapi.com/v1, model uncensored, dan kunci Anda sebagai token bearer:
curl https://api.uncensoredllmapi.com/v1/chat/completions -H "Authorization: Bearer $UNCENSORED_API_KEY" -H "Content-Type: application/json" -d '{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object."},
{"role": "user", "content": "Create a tavern NPC with keys name, trade and rumour."}
]
}'
Pesan asisten di choices[0].message.content adalah string yang berisi objek JSON. Anda masih harus melakukan parsing sendiri. Jangan abaikan instruksi dalam prompt: mode JSON membatasi output agar menjadi objek, tetapi tidak dapat menebak kunci mana yang Anda inginkan. Menamai kunci, dan idealnya menunjukkan contoh satu baris, adalah apa yang memberikan bentuk yang stabil.
Jika Anda belum memiliki kunci, halaman kunci API memberikan $0,50 kredit uji coba dengan satu klik setelah mendaftar. Kredit ini tidak memerlukan pembayaran, berlaku selama 7 hari, dan terbatas satu per orang.
Mode JSON di Python dengan validasi
Perlakukan output model seperti input eksternal lainnya. Parse, periksa terhadap skema, dan coba lagi hingga batas tertentu jika gagal. Pydantic membuat ini singkat:
import json, os
from openai import OpenAI
from pydantic import BaseModel, ValidationError
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
class Npc(BaseModel):
name: str
trade: str
rumour: str
SYSTEM = (
"Reply only with a JSON object with exactly these keys: "
"name, trade, rumour. Each value is a string."
)
def make_npc(setting, tries=3):
for _ in range(tries):
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Setting: {setting}"},
],
temperature=0.7,
max_tokens=300,
)
choice = r.choices[0]
if choice.finish_reason == "length":
continue # cut off, so the JSON is incomplete
try:
return Npc(**json.loads(choice.message.content))
except (json.JSONDecodeError, ValidationError, TypeError):
continue
raise RuntimeError("no valid JSON after retries")
print(make_npc("a river port in a plague year"))
Tiga kebiasaan dalam cuplikan kode tersebut layak untuk ditiru. Kode memeriksa finish_reason sebelum melakukan parsing, karena balasan yang berhenti di max_tokens berakhir di tengah objek. Ini menggunakan suhu moderat, karena suhu tinggi membuat output yang tidak valid lebih mungkin terjadi. Dan ini membatasi percobaan ulang, sehingga prompt yang buruk tidak dapat berputar selamanya. Karena permintaan yang gagal atau ditolak tidak dikenakan biaya, anggaran percobaan ulang adalah pertanyaan latensi, bukan biaya.
Kesalahan umum mode JSON
- Meminta JSON dalam prompt tetapi tidak di
response_format. Model sering akan mematuhi, tetapi mungkin membungkus objek dalam prosa atau pagar kode. Setel keduanya. - Mengatur
max_tokensterlalu rendah. Perkirakan jawaban terpanjang yang valid dan tambahkan margin. Daftar item yang panjang dapat dengan mudah melebihi 300 token. - Mengharapkan array tingkat atas. Mode JSON meminta objek. Jika Anda memerlukan daftar, minta
{"items": [...]}. - Menumpuk urutan berhenti yang muncul dalam JSON. Parameter
stopditeruskan, dan string berhenti yang muncul di dalam nilai akan memotong balasan secara singkat. - Menggunakan mode JSON dengan streaming dan melakukan parsing setiap bagian. Kumpulkan seluruh teks terlebih dahulu, lalu parse sekali di akhir.
Pengaturan sampling seperti temperature, top_p, seed, dan penalti diteruskan. Untuk tugas ekstraksi, suhu rendah sekitar 0,2 dan seed tetap memberikan output yang paling dapat diulang. Untuk generasi kreatif seperti NPC di atas, nilai yang lebih tinggi tidak masalah selama Anda memvalidasi.
Pemanggilan fungsi: loop lengkap
Pemanggilan alat memungkinkan model meminta kode Anda untuk melakukan sesuatu dan kemudian melanjutkan dengan hasilnya. Alur memiliki empat langkah: Anda mendeklarasikan alat, model membalas dengan tool_calls, Anda menjalankannya, dan Anda mengirim hasilnya kembali sebagai pesan dengan role: "tool".
import json, os
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
tools = [{
"type": "function",
"function": {
"name": "lookup_inventory",
"description": "Return the stock count for an item in the shop.",
"parameters": {
"type": "object",
"properties": {"item": {"type": "string"}},
"required": ["item"],
},
},
}]
def lookup_inventory(item):
stock = {"healing potion": 4, "rope": 12}
return {"item": item, "count": stock.get(item.lower(), 0)}
messages = [{"role": "user", "content": "Do you still have healing potions?"}]
for _ in range(4): # hard cap on tool rounds
r = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = r.choices[0].message
if not msg.tool_calls:
print(msg.content)
break
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = lookup_inventory(**args)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
Argumen tiba sebagai string JSON, yang harus Anda parse, dan model kadang-kadang dapat menghasilkan argumen yang tidak sesuai dengan skema Anda. Validasi sebelum menjalankan apa pun yang memiliki efek samping. Jangan pernah meneruskannya ke shell, string SQL, atau path file tanpa pemeriksaan.
Bidang tool_choice memungkinkan Anda mengarahkan perilaku. Biarkan di "auto" dan model memutuskan. Namakan fungsi tertentu untuk memaksa panggilan, yang berguna ketika Anda ingin ekstraksi terstruktur melalui skema alat alih-alih mode JSON.
Streaming pemanggilan fungsi di Node
Dengan stream: true, pemanggilan alat tiba dalam potongan. Setiap bagian membawa fragmen nama fungsi atau string argumen, diindeks berdasarkan posisi. Anda harus menggabungkan fragmen per indeks dan parse hanya ketika streaming berakhir.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.UNCENSORED_API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
stream: true,
messages: [{ role: "user", content: "Check stock for rope." }],
tools: [{
type: "function",
function: {
name: "lookup_inventory",
description: "Return the stock count for an item.",
parameters: {
type: "object",
properties: { item: { type: "string" } },
required: ["item"],
},
},
}],
});
const calls = [];
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta;
for (const tc of delta?.tool_calls ?? []) {
const slot = (calls[tc.index] ??= { id: "", name: "", args: "" });
if (tc.id) slot.id = tc.id;
if (tc.function?.name) slot.name += tc.function.name;
if (tc.function?.arguments) slot.args += tc.function.arguments;
}
}
for (const c of calls) {
console.log(c.name, JSON.parse(c.args));
}
Ingat bahwa permintaan yang di-stream memegang salah satu slot konkurensi Anda hingga streaming berakhir. Kunci penuh memungkinkan 8 permintaan konkuren dan 300 per menit, kunci uji coba 2 dan 60. Mencapai salah satu memberikan HTTP 429 dengan kode concurrency atau rate_limited. Total penggunaan dilaporkan di akhir streaming, yang berguna untuk pencatatan biaya.
Mode JSON atau skema alat
Keduanya memberikan data terstruktur, jadi mana yang harus Anda gunakan? Pertanyaan penentunya adalah apakah model menghasilkan data atau memilih tindakan.
Gunakan mode JSON ketika output itu sendiri adalah produk: lembar NPC, daftar tag, klasifikasi dengan bidang kepercayaan. Anda mengendalikan seluruh prompt, Anda mendapatkan satu objek kembali, dan ada satu permintaan untuk dibayar.
Gunakan alat ketika model harus memutuskan apakah akan bertindak, atau ketika beberapa tindakan berbeda mungkin terjadi. Skema per fungsi mendokumentasikan kontrak, tool_choice memungkinkan Anda memaksa atau mengizinkan panggilan, dan loop di bagian sebelumnya menangani pekerjaan multi-langkah. Biayanya adalah permintaan tambahan per putaran, ditambah definisi alat yang dihitung sebagai input setiap kali.
Jalan tengah praktis untuk ekstraksi: deklarasikan satu alat yang parameternya adalah bidang yang Anda inginkan, dan atur tool_choice ke fungsi tersebut. Anda mendapatkan JSON argumen yang mengikuti bentuk skema Anda tanpa menulis daftar kunci ke dalam prompt. Bagaimanapun juga, validasikan hasilnya sebelum mempercayainya, dan log nilai X-Request-Id dari permintaan apa pun yang menghasilkan sesuatu yang tidak terduga.
Biaya yang dikeluarkan
JSON dan panggilan fungsi ditagih seperti token lainnya: $0,15 per 1M input dan $0,50 per 1M output. Definisi alat dihitung sebagai input pada setiap permintaan, dan setiap hasil alat yang Anda kirim kembali menambah input permintaan berikutnya.
Contoh: giliran asisten menggunakan alat dengan skema alat 600 token dan prompt, panggilan model 150 token, lalu permintaan kedua berisi 900 token input (pesan sebelumnya ditambah hasil alat) dan balasan 200 token.
- Permintaan satu: 600 input dan 150 output. Input 600 x $0,15 / 1M = $0,00009. Output 150 x $0,50 / 1M = $0,000075. Subtotal $0,000165.
- Permintaan dua: 900 input dan 200 output. Input 900 x $0,15 / 1M = $0,000135. Output 200 x $0,50 / 1M = $0,0001. Subtotal $0,000235.
- Total untuk putaran: $0.0004.
Pada laju tersebut, 1.000 putaran biaya $0,40. Saldo prabayar dalam jumlah bulat dari $20 hingga $500 (bonus: +5% dari $50, +10% dari $100, +15% dari $200), dibayar dengan kripto menggunakan USDT di TRC20 atau USDC di Base. Lihat halaman harga untuk angka terkini.
Langkah selanjutnya
Referensi untuk setiap bidang permintaan ada di dokumentasi API. Jika Anda menyiapkan aplikasi untuk lalu lintas nyata, checklist produksi adalah halaman berikutnya yang harus dibaca, dan dukungan dapat membantu jika permintaan berperilaku tidak terduga. Simpan ID permintaan Anda, yang muncul kembali di header X-Request-Id, agar mudah diakses.
Layanan ini hanya teks dan jendela konteks adalah 100.000 token, termasuk definisi dan hasil alat Anda. Konten seksual yang melibatkan anak di bawah umur tidak diperbolehkan, dan itu berlaku untuk output terstruktur dan berbasis alat sama seperti halnya chat biasa.
