เริ่มต้นใช้งานด้วย curl
คำขอโหมด JSON ที่ทำงานได้เล็กที่สุดมีลักษณะดังนี้ ใช้ Base URL https://api.uncensoredllmapi.com/v1 โมเดล uncensored และคีย์ของคุณเป็น bearer token:
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."}
]
}'
ข้อความของผู้ช่วยใน choices[0].message.content เป็นสตริงที่มีวัตถุ JSON คุณต้องทำการแยกวิเคราะห์ (parse) ด้วยตนเอง อย่าข้ามคำแนะนำในพรอมต์: โหมด JSON จำกัดผลลัพธ์ให้เป็นวัตถุ แต่โมเดลไม่สามารถเดาคีย์ที่คุณต้องการได้ การระบุชื่อคีย์ และแสดงตัวอย่างแบบสั้นๆ จะช่วยให้โครงสร้างมีความเสถียร
หากคุณยังไม่มีคีย์ API หน้าคีย์ API จะมอบเครดิตทดลองใช้ $0.50 ให้เพียงคลิกเดียวหลังการสมัครสมาชิก เครดิตนี้ไม่ต้องใช้เงิน ใช้ได้ 7 วัน และจำกัดหนึ่งต่อบุคคล
โหมด JSON ใน Python พร้อมการตรวจสอบความถูกต้อง
จัดการกับผลลัพธ์จากโมเดลเหมือนข้อมูลภายนอกทั่วไป แยกวิเคราะห์ ตรวจสอบกับสคีมา และลองใหม่จำนวนจำกัดหากไม่สำเร็จ Pydantic ทำให้กระบวนการนี้สั้นลง:
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"))
สามนิสัยในโค้ดตัวอย่างนี้ควรค่าแก่การคัดลอก โค้ดตรวจสอบ finish_reason ก่อนทำการแยกวิเคราะห์ เนื่องจากคำตอบที่หยุดที่ max_tokens จะทำให้วัตถุไม่สมบูรณ์ ใช้ค่า temperature ที่ปานกลาง เนื่องจากค่าสูงทำให้ผลลัพธ์ที่ผิดรูปแบบมีโอกาสเกิดขึ้นมากขึ้น และจำกัดจำนวนการลองใหม่ เพื่อให้พรอมต์ที่ผิดพลาดไม่ทำให้เกิดการวนลูปไม่สิ้นสุด เนื่องจากคำขอที่ล้มเหลวหรือถูกปฏิเสธจะไม่ถูกเรียกเก็บเงิน งบประมาณการลองใหม่จึงเป็นเรื่องของเวลาแฝง (latency) ไม่ใช่ต้นทุน
ข้อผิดพลาดทั่วไปของโหมด JSON
- การขอ JSON ในพรอมต์แต่ไม่ระบุใน
response_formatโมเดลมักจะยอม แต่อาจ wrap object ในข้อความหรือ code fence ตั้งค่าทั้งสองอย่าง - การตั้งค่า
max_tokensต่ำเกินไป ประมาณการคำตอบที่ถูกต้องที่ยาวที่สุดแล้วเพิ่มระยะปลอดภัย รายการยาวๆ สามารถเกิน 300 tokens ได้ง่าย - คาดหวังอาร์เรย์ระดับบนสุด โหมด JSON ต้องการวัตถุ หากต้องการรายการ ให้ขอ
{"items": [...]} - การตั้งลำดับหยุด (stop sequence) ที่ปรากฏอยู่ใน JSON พารามิเตอร์
stopจะถูกส่งผ่าน และสตริงหยุดที่ปรากฏภายในค่าจะตัดการตอบกลับให้สั้นลง - การใช้โหมด JSON พร้อม streaming และการ parse แต่ละ chunk รวบรวมข้อความทั้งหมดก่อน แล้วจึง parse ครั้งเดียวที่ท้ายสุด
การตั้งค่า sampling เช่น temperature, top_p, seed และค่าปรับจะถูกส่งผ่าน สำหรับงาน extraction ค่า temperature ต่ำประมาณ 0.2 และ seed คงที่ ให้ผลลัพธ์ที่ซ้ำกันได้มากที่สุด สำหรับการสร้างเนื้อหาสร้างสรรค์เช่น NPC ด้านบน ค่าที่สูงกว่าก็ใช้ได้ ตราบใดที่คุณ validate
การเรียกใช้ฟังก์ชัน: วงจรเต็ม
การเรียกใช้ฟังก์ชันช่วยให้โมเดลขอให้คุณรันโค้ดแล้วดำเนินการต่อด้วยผลลัพธ์ ขั้นตอนมีสี่ขั้นตอน: คุณประกาศเครื่องมือ โมเดลตอบกลับด้วย tool_calls คุณรันเครื่องมือเหล่านั้น แล้วส่งผลลัพธ์กลับเป็น messages ด้วย 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),
})
อาร์กิวเมนต์มาถึงเป็นสตริง JSON ซึ่งคุณต้องทำการแยกวิเคราะห์ และโมเดลอาจผลิตอาร์กิวเมนต์ที่ไม่ตรงกับสคีมาของคุณ ตรวจสอบอาร์กิวเมนต์ก่อนดำเนินการใดๆ ที่มีผลข้างเคียง อย่าส่งอาร์กิวเมนต์ไปยังเชลล์ สตริง SQL หรือพาธไฟล์โดยไม่มีการตรวจสอบ
ฟิลด์ tool_choice ช่วยให้คุณควบคุมพฤติกรรม ตั้งเป็น "auto" และโมเดลจะตัดสินใจ ตั้งชื่อฟังก์ชันเฉพาะเพื่อบังคับการเรียกใช้ ซึ่งมีประโยชน์เมื่อคุณต้องการสกัดข้อมูลเชิงโครงสร้างผ่านสคีมาของเครื่องมือ แทนโหมด JSON
สตรีมมิงการเรียกใช้ฟังก์ชันใน Node
ด้วย stream: true การเรียกใช้เครื่องมือจะมาเป็นชิ้นส่วน แต่ละชิ้นมีส่วนของชื่อฟังก์ชันหรือสตริงอาร์กิวเมนต์ ซึ่งจัดดัชนีตามตำแหน่ง คุณต้องต่อชิ้นส่วนตามดัชนี และแยกวิเคราะห์เฉพาะเมื่อสตรีมจบ
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));
}
จำไว้ว่าคำขอ streamed จะถือ concurrency slot หนึ่งของคุณจนกว่า stream จะจบ คีย์เต็มอนุญาตให้ concurrent requests ได้ 8 รายการและ 300 ต่อนาที คีย์ทดลองอนุญาต 2 และ 60 การชนกับขีดจำกัดใด ๆ จะให้ HTTP 429 พร้อมรหัส concurrency หรือ rate_limited ยอดการใช้งานรวมจะรายงานเมื่อสตรีมสิ้นสุด ซึ่งสะดวกสำหรับการบันทึกต้นทุน
โหมด JSON หรือสคีมาของเครื่องมือ
ทั้งสองแบบให้ข้อมูลที่มีโครงสร้าง ดังนั้นคุณควรใช้แบบไหน? คำถามสำคัญคือโมเดลกำลังสร้างข้อมูลหรือกำลังเลือกการกระทำ
ใช้โหมด JSON เมื่อผลลัพธ์คือผลิตภัณฑ์: ใบตัวละคร NPC รายการแท็ก หรือการจำแนกประเภทที่มีฟิลด์ความมั่นใจ คุณควบคุมพรอมต์ทั้งหมด รับวัตถุเดียวกลับคืนมา และมียอดคำขอที่ต้องจ่ายเพียงรายการเดียว
ใช้เครื่องมือเมื่อโมเดลต้องตัดสินใจว่าจะดำเนินการหรือไม่ หรือเมื่อมีการดำเนินการที่แตกต่างกันหลายอย่าง สคีมาต่อฟังก์ชันจะบันทึกสัญญาการใช้งาน tool_choice ช่วยให้บังคับหรืออนุญาตการเรียกใช้ และลูปในส่วนก่อนหน้าจัดการงานหลายขั้นตอน ต้นทุนคือคำขอเพิ่มเติมต่อรอบ รวมถึงนิยามเครื่องมือที่นับเป็นอินพุตทุกครั้ง
ทางสายกลางที่ใช้ได้จริงสำหรับการสกัดข้อมูล: ประกาศเครื่องมือหนึ่งตัวที่มีพารามิเตอร์เป็นฟิลด์ที่คุณต้องการ และตั้งค่า tool_choice เป็นฟังก์ชันนั้น คุณจะได้ JSON ของอาร์กิวเมนต์ที่สอดคล้องกับโครงสร้างสคีมาของคุณโดยไม่ต้องเขียนรายการคีย์ลงในพรอมต์ ไม่ว่าทางไหน ให้ตรวจสอบผลลัพธ์ก่อนที่คุณจะเชื่อถือ และบันทึกค่า X-Request-Id ของคำขอใดๆ ที่ให้ผลลัพธ์ไม่คาดคิด
ต้นทุน
JSON และการเรียกใช้เครื่องมือจะคิดค่าใช้จ่ายเหมือนโทเคนอื่นๆ: $0.15 ต่อ 1M input และ $0.50 ต่อ 1M output นิยามเครื่องมือนับเป็นอินพุตในทุกคำขอ และผลลัพธ์จากเครื่องมือแต่ละรายการที่คุณส่งกลับจะเพิ่มเข้าไปในอินพุตของคำขอถัดไป
ตัวอย่าง: การตอบกลับของอัสซิสแตนต์ที่ใช้เครื่องมือด้วยสคีมาของเครื่องมือและพรอมต์ขนาด 600 โทเคน การเรียกโมเดลขนาด 150 โทเคน จากนั้นคำขอครั้งที่สองที่มีโทเคนอินพุต 900 โทเคน (ข้อความก่อนหน้าบวกกับผลลัพธ์จากเครื่องมือ) และการตอบกลับขนาด 200 โทเคน
- คำขอหนึ่ง: ข้อมูลนำเข้า 600 และข้อมูลส่งออก 150 ข้อมูลนำเข้า 600 x $0.15 / 1M = $0.00009 ข้อมูลส่งออก 150 x $0.50 / 1M = $0.000075 ยอดรวมย่อย $0.000165
- คำขอสอง: ข้อมูลนำเข้า 900 และข้อมูลส่งออก 200 ข้อมูลนำเข้า 900 x $0.15 / 1M = $0.000135 ข้อมูลส่งออก 200 x $0.50 / 1M = $0.0001 ยอดรวมย่อย $0.000235
- รวมสำหรับรอบ: $0.0004.
ในอัตรานี้ การทำ 1,000 turns มีค่าใช้จ่าย $0.40 เครดิตเป็นแบบเติมเงินล่วงหน้าเป็นจำนวนเต็มตั้งแต่ $20 ถึง $500 (โบนัส: +5% จาก $50, +10% จาก $100, +15% จาก $200) จ่ายด้วยคริปโตด้วย USDT บน TRC20 หรือ USDC บน Base ดูหน้า ราคาเพื่อดูตัวเลขปัจจุบัน
ขั้นตอนถัดไป
ข้อมูลอ้างอิงสำหรับฟิลด์แต่ละฟิลด์ในคำขออยู่ใน เอกสาร API หากคุณกำลังเตรียมแอปพลิเคชันสำหรับการใช้งานจริง หน้า รายการตรวจสอบสำหรับ productionคือหน้าที่ต้องอ่านถัดไป และ ฝ่ายสนับสนุนสามารถช่วยเหลือได้หากคำขอทำงานผิดปกติ ให้เก็บ ID คำขอของคุณซึ่งจะกลับมาใน header X-Request-Id ให้พร้อมใช้งาน
บริการเป็นแบบข้อความเท่านั้น และหน้าต่างบริบทคือ 100,000 โทเคน ซึ่งรวมถึงการกำหนดเครื่องมือและผลลัพธ์ของคุณ เนื้อหาทางเพศที่เกี่ยวข้องกับผู้เยาว์ไม่อนุญาต และกฎนี้ใช้กับผลลัพธ์แบบมีโครงสร้างและแบบใช้เครื่องมือเหมือนกับข้อความแชททั่วไป
