بداية سريعة باستخدام curl
يبدو أصغر طلب يعمل في وضع JSON هكذا. يستخدم عنوان URL الأساسي https://api.uncensoredllmapi.com/v1، والنموذج uncensored، ومفتاحك كرمز 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."}
]
}'
رسالة المساعد في choices[0].message.content هي سلسلة نصية تحتوي على كائن JSON. لا يزال عليك تحليلها بنفسك. لا تتخطَ التعليمات في الموجّه: يفرض وضع JSON أن يكون المخرج كائناً، لكنه لا يستطيع تخمين المفاتيح التي تريدها. تسمية المفاتيح، وإظهار مثال مختصر في سطر واحد، هو ما يمنحك شكلاً مستقراً.
إذا لم يكن لديك مفتاح بعد، فإن صفحة مفتاح 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 ينتهي في منتصف الكائن. يستخدم درجة حرارة معتدلة، لأن درجات الحرارة العالية تزيد من احتمالية المخرجات غير الصالحة. ويحد من عمليات إعادة المحاولة، حتى لا يؤدي الـ prompt السيئ إلى حلقة لا نهائية. بما أن الطلبات الفاشلة أو المرفوضة لا تُحسب، فإن ميزانية إعادة المحاولة هي مسألة زمن استجابة وليست تكلفة.
أخطاء شائعة في وضع JSON
- طلب JSON في الموجّه ولكن ليس في
response_format. غالباً ما يمتثل النموذج، لكنه قد يلف الكائن في نص عادي أو في كتلة كود. اضبط كلاهما. - ضبط
max_tokensمنخفضاً جداً. قدّر أطول إجابة صالحة وأضف هامشاً. قد تتجاوز قائمة طويلة من العناصر بسهولة 300 رمز. - توقع مصفوفة في المستوى الأعلى. يطلب وضع JSON كائناً. إذا كنت بحاجة إلى قائمة، اطلب
{"items": [...]}. - تراكب تسلسل توقف يظهر داخل JSON. يتم تمرير المعلمة
stopكما هي، وسلسلة التوقف التي تظهر داخل قيمة ستقطع الرد مبكراً. - استخدام وضع JSON مع البث وتحليل كل قطعة. اجمع النص الكامل أولاً، ثم قم بالتحليل مرة واحدة في النهاية.
تُمرَّر إعدادات العينات مثل درجة الحرارة وtop_p وseed والعقوبات كما هي. بالنسبة لمهام الاستخراج، تعطي درجة حرارة منخفضة تبلغ حوالي 0.2 وseed ثابتة seed أكثر المخرجات تكرارًا. بالنسبة للتوليد الإبداعي مثل NPC المذكور أعلاه، فإن قيمة أعلى مقبولة طالما قمت بالتحقق.
استدعاء الدوال: الحلقة الكاملة
يسمح استدعاء الدوال للنموذج بطلب كودك للقيام بشيء ما ثم الاستمرار بالنتيجة. تتدفق العملية في أربع خطوات: تعلن عن الأدوات، يرد النموذج بـ tool_calls، تقوم بتشغيلها، وترسل النتائج مرة أخرى كرسائل مع 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));
}
تذكر أن الطلب المتدفق يحتفظ بإحدى فتحات التزامن الخاصة بك حتى ينتهي البث. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 في الدقيقة، بينما يسمح المفتاح التجريبي بـ 2 و60. سيؤدي تجاوز أي منهما إلى HTTP 429 مع الكود concurrency أو rate_limited. تُبلغ إجماليات الاستخدام في نهاية البث، وهو أمر مفيد لتسجيل التكلفة.
وضع JSON أو مخطط الأداة
كلاهما يوفر لك بيانات مُهيكلة، لذا أيهما يجب أن تستخدم؟ السؤال الحاسم هو ما إذا كان النموذج يُنتج بيانات أم يختار إجراءً.
استخدم وضع JSON عندما يكون المخرج نفسه هو المنتج: ورقة لشخصية غير لاعبة (NPC)، قائمة وسوم، تصنيف مع حقل ثقة. أنت تتحكم في كامل الموجّه، وتعود لك كائن واحد، وهناك طلب واحد للدفع مقابله.
استخدم الأدوات عندما يحتاج النموذج إلى اتخاذ قرار بشأن الفعل، أو عندما تكون هناك إجراءات مختلفة متعددة ممكنة. يوثق مخطط لكل دالة العقد، ويسمح tool_choice بإجبار أو السماح بالاستدعاء، وتتعامل الحلقة في القسم السابق عن العمل متعدد الخطوات. التكلفة هي طلب إضافي لكل جولة، بالإضافة إلى تعريفات الأدوات التي تُحسب كمدخلات في كل مرة.
مسار عملي للاستخراج: أعلن أداةً واحدةً تكون معاملاتها هي الحقول التي تريدها، واضبط tool_choice لتلك الدالة. تحصل على JSON للمعاملات يتبع شكل المخطط الخاص بك دون كتابة قائمة المفاتيح في الموجّه. في كلتا الحالتين، تحقق من النتيجة قبل الوثوق بها، وسجّل قيمة X-Request-Id لأي طلب أنتج شيئًا غير متوقع.
التكلفة
تُحسب تكاليف JSON واستدعاءات الأدوات مثل أي رموز أخرى: $0.15 لكل مليون إدخال و $0.50 لكل مليون إخراج. تُحسب تعريفات الأدوات كمدخلات في كل طلب، ويضيف كل نتيجة أداة ترسلها إلى مدخلات الطلب التالي.
مثال: دور مساعد يستخدم الأدوات مع مخطط أداة وموجّه بحجم 600 رمز، استدعاء نموذج بحجم 150 رمز، ثم طلب ثانٍ يحتوي على 900 رمز مدخل (الرسائل السابقة بالإضافة إلى نتيجة أداة) و200 رمز رد.
- الطلب الأول: 600 مدخل و150 مخرج. المدخلات 600 × $0.15 / 1M = $0.00009. المخرجات 150 × $0.50 / 1M = $0.000075. المجموع الفرعي $0.000165.
- الطلب الثاني: 900 مدخل و200 مخرج. المدخلات 900 × $0.15 / 1M = $0.000135. المخرجات 200 × $0.50 / 1M = $0.0001. المجموع الفرعي $0.000235.
- المجموع للدورة: $0.0004.
بمعدل ذلك، تكلف 1,000 دورة $0.40. الرصيد مسبق الدفع بمبالغ صحيحة من $20 إلى $500 (مكافأة: +5% من $50، +10% من $100، +15% من $200)، مدفوع بالعملات المشفرة باستخدام USDT على TRC20 أو USDC على Base. انظر صفحة التسعير للحصول على الأرقام الحالية.
إلى أين تذهب بعد ذلك
مرجع لكل حقل طلب موجود في وثائق API. إذا كنت تعدّ تطبيقًا لحركة المرور الحقيقية، فإن قائمة التحقق للإنتاج هي الصفحة التالية التي يجب قراءتها، ويمكن لـ الدعم المساعدة إذا تصرف الطلب بشكل غير متوقع. احتفظ بمعرف الطلب الخاص بك، الذي يعود في رأس X-Request-Id، في متناول يدك.
الخدمة نصية فقط، ونافذة السياق هي 100,000 رمز، بما في ذلك تعريفات أدواتك ونتائجها. المحتوى الجنسي الذي يتضمن قاصرين غير مسموح به، وهذا ينطبق على المخرجات المهيكلة والمعتمدة على الأدوات تمامًا كما ينطبق على الدردشة العادية.
