أمثلة استدعاء API للذكاء الاصطناعي بدون رقابة: كود كامل لـ Python، Node.js و cURL

معلومات الواجهة الأساسية ومتغيرات البيئة

احفظ بعض المعلمات الثابتة أولاً، حيث ستُستخدم في جميع الأمثلة التالية. Base URL هو https://api.wuxianzhiapi.com/v1، واسم النموذج ثابت على uncensored، وطريقة المصادقة هي رأس الطلب Authorization: Bearer <المفتاح>. هناك واجهتان فقط: POST /v1/chat/completions للمحادثات، و GET /v1/models للتحقق من توفر النموذج. تنسيق الطلب والاستجابة مطابق لـ Chat Completions من OpenAI، لذا يتطلب SDK الرسمي openai فقط تغيير base_url والمفتاح، دون الحاجة لتعديل كود العمل.

يظهر المفتاح فور التسجيل في /get-api-key/، باستخدام البريد الإلكتروني وكلمة المرور فقط. يحتوي الحساب الجديد على رصيد تجريبي مجاني بقيمة $0.50 صالح لمدة 7 أيام، دون الحاجة لربط بطاقة. تُقرأ مفاتيح API في جميع أمثلة هذا الدليل من متغير البيئة WUXIANZHI_API_KEY، لذا لا تكتب المفتاح في مستودع الكود أو في صفحات الواجهة الأمامية. هناك بعض القيود: نافذة السياق 100,000 رمز (مجموع الموجّه والمخرجات)، حجم جسم الطلب لا يتجاوز 8 MB، و 300 طلب في الدقيقة لكل مفتاح.

复制export WUXIANZHI_API_KEY="把你的密钥放这里"

# 确认连通性，应返回包含 uncensored 的模型列表
curl https://api.wuxianzhiapi.com/v1/models \
  -H "Authorization: Bearer $WUXIANZHI_API_KEY"

إذا عادت الاستجابة بـ 401، فهذا يعني أن المفتاح غير صحيح أو أن متغير البيئة لم يُفعّل، تحقق من هذه النقطة أولاً قبل متابعة قراءة الكود. لمزيد من التفاصيل حول المعاملات، راجع وثائق الواجهة.

cURL: طلب الحد الأدنى القابل للتشغيل

بغض النظر عن اللغة التي ستستخدمها في النهاية، يُنصح بتشغيل طلب واحد عبر cURL أولاً. هذا يعزل مشاكل «الشبكة، المفتاح، تنسيق الطلب» عن كود العمل الخاص بك. فيما يلي طلب عادي يتضمن max_tokens. يحتوي JSON الناتج على نص الرد في choices[0].message.content، وبيانات الاستهلاك في usage، والتي تُحسب عليها التكلفة.

复制curl https://api.wuxianzhiapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WUXIANZHI_API_KEY" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "你是一个直来直去的写作助手。"},
      {"role": "user", "content": "用三句话描述一场暴雨前的小镇。"}
    ],
    "max_tokens": 300
  }'

لا حاجة للتهرب اليدوي من النصوص الصينية في JSON، ما دمت قد أعلنت دعم UTF-8 للـ JSON في رؤوس الطلب، ويمكنك لصق الطلب مباشرة في معظم وحدات التحكم. إذا كنت تستخدم PowerShell على Windows، فإن معالجة علامات الاقتباس معقدة، لذا يُنصح بحفظ جسم الطلب في ملف body.json وإرساله باستخدام -d @body.json.

الاستدعاء الكامل لـ Python و Node.js

يستخدم Python الحزمة الرسمية openai (الإصدار 1 فأعلى)، قم أولاً بـ pip install openai. عند إنشاء العميل، مرر base_url و api_key، ثم تكون طريقة الاستدعاء مطابقة تماماً لاستدعاء OpenAI. يمكنك حفظ السكربت التالي باسم chat.py وتشغيله مباشرة.

复制import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "你是一个直来直去的写作助手。"},
        {"role": "user", "content": "用三句话描述一场暴雨前的小镇。"},
    ],
    max_tokens=300,
)

print(resp.choices[0].message.content)
print("输入 tokens:", resp.usage.prompt_tokens, "输出 tokens:", resp.usage.completion_tokens)

يستخدم Node.js حزمة npm لـ openai (الإصدار 4 فأعلى)، قم بـ npm install openai. يستخدم الأسلوب أدناه الكلمة المفتاحية await في المستوى الأعلى، لذا احفظ الملف باسم chat.mjs، أو اضبط "type": "module" في package.json.

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.wuxianzhiapi.com/v1",
  apiKey: process.env.WUXIANZHI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "system", content: "你是一个直来直去的写作助手。" },
    { role: "user", content: "用三句话描述一场暴雨前的小镇。" },
  ],
  max_tokens: 300,
});

console.log(resp.choices[0].message.content);
console.log("用量:", resp.usage);

هيكل الكودين متطابق، والفرق يكمن في الصياغة فقط. إذا كان لديك بالفعل استدعاءات لـ OpenAI في مشروعك، فغالباً ما يكفي استبدال أسطر تهيئة العميل وتغيير اسم النموذج إلى uncensored. لمزيد من خطوات الترحيل من واجهات أخرى، راجع دليل الترحيل.

كيفية قراءة البث المتدفق (SSE)

عند كتابة نصوص طويلة أو بناء واجهات دردشة، يجب استخدام البث المتدفق، وإلا سيضطر المستخدم للانتظار حتى اكتمال التوليد لرؤية الحرف الأول. بعد تعيين stream: true، سيرسل الخادم البيانات على شكل كتف عبر SSE (Server-Sent Events)، حيث يكون كل كتف سطر data: {...}، وينتهي بـ data: [DONE]. يقوم SDK الرسمي بتحليل البيانات نيابة عنك، وعليك فقط التكرار عبر النتائج.

هناك تفصيل قد يسبب مشاكل: يتم إضافة كتيف بيانات تلقائي في نهاية البث يحتوي على usage، حيث تكون choices مصفوفة فارغة. لا تحتاج لتمرير معلمة لتفعيله، لكن لا تفترض في الكود أن chunk.choices[0] موجود دائماً، بل تحقق من الفارغية أولاً لتجنب خطأ تجاوز حدود المصفوفة عند اقتراب نهاية البث.

复制import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
)

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一段 200 字左右的悬疑小说开头。"}],
    max_tokens=600,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.usage:            # 最后一块：用量统计
        usage = chunk.usage
    if not chunk.choices:      # 用量块没有 choices
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

print()
if usage:
    print("输入", usage.prompt_tokens, "输出", usage.completion_tokens)

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.wuxianzhiapi.com/v1",
  apiKey: process.env.WUXIANZHI_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "写一段 200 字左右的悬疑小说开头。" }],
  max_tokens: 600,
  stream: true,
});

let usage = null;
for await (const chunk of stream) {
  if (chunk.usage) usage = chunk.usage;
  const delta = chunk.choices?.[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}
console.log("\n用量:", usage);

لمراقبة بيانات SSE الخام، استخدم cURL مع المعلمة -N لإيقاف تخزين المخرجات مؤقتاً، مما يطبع كل كتف فور وصوله. هذا مفيد جداً عند تصحيح الأخطاء للتحقق مما إذا كان الوكيل أو البوابة يبتلع استجابة البث المتدفق.

复制curl -N https://api.wuxianzhiapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WUXIANZHI_API_KEY" \
  -d '{"model":"uncensored","stream":true,"max_tokens":100,
       "messages":[{"role":"user","content":"数到五。"}]}'

إذا كنت تعيد توجيه استجابة البث المتدفق خلف وكيل عكسي مثل Nginx، فتأكد من إيقاف تخزين المخرجات مؤقتاً لهذا المسار، وإلا سترى الواجهة الأمامية البيانات دفعة واحدة بدلاً من ظهورها حرفاً بحرف.

استدعاء الدوال: tools وإرجاع نتائج الأدوات

يعتمد استدعاء الدوال على تنسيق OpenAI: في الطلب، أعلن عن أسماء الدوال ووصفها ومعاملات JSON Schema باستخدام tools. عندما يقرر النموذج استدعاء دالة، سيضع اسم الدالة ومعاملات كسلسلة JSON في message.tool_calls. يتولى كودك تنفيذ الدالة فعلياً، ثم إرسال النتيجة كرسالة role: "tool"، وطلب الاستجابة مرة أخرى، ليقوم النموذج بكتابة الإجابة النهائية بناءً على النتيجة.

يكون tool_choice افتراضياً على "auto"، ليقرر النموذج بنفسه؛ لإجبار استدعاء دالة معينة، مرر {"type": "function", "function": {"name": "get_weather"}}؛ ومرر "none" لمنع الاستدعاء تماماً. يوضح المثال التالي دورة كاملة: الحصول على tool_calls في الطلب الأول، تنفيذ الدالة محلياً، ثم إرسال نتائج الأدوات في الطلب الثاني.

复制import json, os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
)

def get_weather(city: str) -> dict:
    # 这里用假数据代替真实的天气接口
    return {"city": city, "temp_c": 18, "condition": "多云"}

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "城市名"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "杭州现在天气怎么样？"}]

first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto", max_tokens=500
)
msg = first.choices[0].message

if msg.tool_calls:
    messages.append(msg)  # 必须把带 tool_calls 的 assistant 消息原样放回历史
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })
    final = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools, max_tokens=500
    )
    print(final.choices[0].message.content)
else:
    print(msg.content)

ثلاثة أخطاء شائعة: أولاً، نسيان وضع رسالة tool_calls الخاصة بـ assistant في التاريخ، مما يجعل الطلب غير صالح. ثانياً، عدم تطابق tool_call_id. ثالثاً، يجب تحويل معاملات النموذج من نص باستخدام json.loads، مع معالجة أخطاء التحميل لتجنب دمج المخرجات مباشرة في الأوامر أو SQL. نفس المنطق ينطبق على Node.js.

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.wuxianzhiapi.com/v1",
  apiKey: process.env.WUXIANZHI_API_KEY,
});

const getWeather = (city) => ({ city, temp_c: 18, condition: "多云" });

const tools = [{
  type: "function",
  function: {
    name: "get_weather",
    description: "查询指定城市的当前天气",
    parameters: {
      type: "object",
      properties: { city: { type: "string", description: "城市名" } },
      required: ["city"],
    },
  },
}];

const messages = [{ role: "user", content: "杭州现在天气怎么样？" }];

const first = await client.chat.completions.create({
  model: "uncensored", messages, tools, tool_choice: "auto", max_tokens: 500,
});
const msg = first.choices[0].message;

if (msg.tool_calls?.length) {
  messages.push(msg);
  for (const call of msg.tool_calls) {
    const args = JSON.parse(call.function.arguments);
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(getWeather(args.city)),
    });
  }
  const final = await client.chat.completions.create({
    model: "uncensored", messages, tools, max_tokens: 500,
  });
  console.log(final.choices[0].message.content);
} else {
  console.log(msg.content);
}

معالجة الأخطاء وإعادة المحاولة: التراجع لـ 429 و 503

استجابات الخطأ كلها JSON موحّد: {"error":{"code":...,"message":...}}. في الكود، النوعان الوحيدان اللذان يستحقان إعادة المحاولة هما: 429 (تجاوز حدّ المعدل 300 طلب/دقيقة) و 503 (upstream_busy، النموذج مشغول مؤقتاً، حاول بعد ثوانٍ). استحقّ أيضاً إعادة محاولة تجاوز الاتصال على مستوى الشبكة. إعادة المحاولة لباقي الأخطاء لا طائل منها: 400 يعني مشكلة في الطلب نفسه (مثل تجاوز النص الموجه لـ max_tokens 100k)، 401 يعني مفتاح API غير صالح، 402 no_credit يعني نفاد الرصيد أو انتهاء التجربة، 403 content_blocked يعني حجب المحتوى، إعادة الإرسال لن تغير النتيجة.

استخدم استراتيجية التراجع الأسي مع زخم عشوائي: انتظر حوالي ثانية واحدة للمحاولة الأولى، و 2 ثوانٍ للمحاولة الثانية، و 4 ثوانٍ للمحاولة الثالثة، مع تحديد حد أقصى وعدد محاولات أقصى لتجنب إعادة محاولة عدة مهام متزامنة في نفس الوقت، مما يفاقم مشكلة حدّ المعدل. يحتوي SDK الرسمي على max_retries، والذي يعيد المحاولة لعدد قليل من المرات لـ 429 و 5xx، وفي السيناريوهات البسيطة يمكنك زيادة هذا الرقم مباشرة؛ أما إذا كنت تحتاج إلى تسجيل السجلات أو الدرع أو تحديد وقت انتظار مخصص، فقم بكتابة حلقة إعادة المحاولة بنفسك.

复制import os, random, time
import openai
from openai import OpenAI

# max_retries=0：关闭 SDK 自带重试，完全由下面的函数控制
client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
    max_retries=0,
    timeout=60,
)

def chat_with_retry(messages, max_attempts=5, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(
                model="uncensored", messages=messages, **kwargs
            )
        except (openai.RateLimitError, openai.InternalServerError,
                openai.APIConnectionError, openai.APITimeoutError) as e:
            if attempt == max_attempts - 1:
                raise
            wait = min(30, 2 ** attempt) + random.uniform(0, 1)
            print(f"{type(e).__name__}，{wait:.1f} 秒后重试（第 {attempt + 1} 次）")
            time.sleep(wait)
        except openai.APIStatusError as e:
            # 400 / 401 / 402 / 403 / 404：重试无效，直接交给上层处理
            print("不可重试:", e.status_code, e.response.text)
            raise

resp = chat_with_retry([{"role": "user", "content": "你好"}], max_tokens=100)
print(resp.choices[0].message.content)

في Node.js، يمكنك أيضاً زيادة maxRetries مباشرة، حيث سيتعامل SDK مع 429 و 5xx وفقاً لاستراتيجية التراجع. للتمييز بين الأخطاء، استخدم error.status.

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.wuxianzhiapi.com/v1",
  apiKey: process.env.WUXIANZHI_API_KEY,
  maxRetries: 5,
  timeout: 60_000,
});

try {
  const resp = await client.chat.completions.create({
    model: "uncensored",
    messages: [{ role: "user", content: "你好" }],
    max_tokens: 100,
  });
  console.log(resp.choices[0].message.content);
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    if (err.status === 402) console.error("余额不足，请充值后再试");
    else if (err.status === 403) console.error("内容被拦截:", err.message);
    else console.error("请求失败:", err.status, err.message);
  } else {
    throw err;
  }
}

ملاحظة إضافية: عند انقطاع طلب البث المتدفق، يجب الاحتفاظ بالمحتوى الذي تم استلامه بالفعل، لأن إعادة المحاولة ستبدأ التوليد من البداية وتعيد الفوترة، لذا يُنصح بتقسيم توليد النصوص الطويلة إلى طلبات متعددة بدلاً من طلب نص طويل في طلب واحد.

التحكم في التكلفة والطول عبر max_tokens

قواعد الفوترة مباشرة: الإدخال $0.25 / مليون رمز، والإخراج $1.00 / مليون رمز، مع رصيد مسبق الدفع، بدون رسوم شهرية، ولا ينتهي الرصيد. سعر الإخراج أعلى 4 مرات من سعر الإدخال، لذا فإن توفير التكلفة الحقيقي يكمن في التحكم في المخرجات. يكون max_tokens افتراضياً على 2048، والحد الأقصى لطلب واحد هو 32,000. إذا كان سيناريو عملك يتطلب رداً بجملة أو اثنتين فقط، حدد القيمة بـ 200 أو 300، مما يمنع النموذج من الإطالة ويحدد سقف تكلفة الطلب الواحد.

لنحسب التكلفة: ضبط max_tokens على 1,000، التكلفة الأسوأ للإخراج هي $0.001؛ ضبطه على الحد الأقصى 32,000، التكلفة الأسوأ هي $0.016. رصيد التجربة $0.50 يعادل تقريباً 500k رمز (token) للإخراج، أو 2 مليون رمز للإدخال، وهذا كافٍ لتشغيل جميع أمثلة المقال مرات عديدة. انتبه إلى أن مجموع النص الموجه و max_tokens يجب ألا يتجاوز 100,000، وإلا ستحصل على 400 مباشرة، لذا عند طول النص المدخل، خفّض حدّ الإخراج. لمزيد من التفاصيل، راجع صفحة الأسعار.

تفصيل آخر: إذا تم قطع الرد، فسيكون finish_reason في الاستجابة هو "length"، مما يعني أن max_tokens لم يكن كافياً، وليس أن النموذج أنهى الكتابة بنفسه. عند كتابة نصوص طويلة، يمكنك فحص هذا الحقل لتحديد ما إذا كنت تريد الاستمرار في الكتابة.

المحادثات المتعددة: الحفاظ على السياق بنفسك

الواجهة نفسها عديمة الحالة، ولا يتذكر الخادم الطلب السابق. لمواصلة المحادثة مع النموذج، يجب إعادة إرسال سجل الرسائل الكامل بالترتيب في كل طلب: يبدأ بـ system، ثم يتناوب user و assistant. هذا يعني أن كل حلقة جديدة تزيد من عدد رموز الإدخال، مما يراكم التكلفة، وتصبح تكلفة الإدخال في كل حلقة لاحقة أعلى من الحلقات السابقة.

يتم تقييد إجمالي حجم السياق بـ 100,000 رمز (token) (بما في ذلك المخرجات الحالية)، لذا يجب تقصير المحادثات الطويلة. أبسط طريقة هي الاحتفاظ برسالة النظام والدورات الأخيرة؛ وبشكل أكثر تعقيداً، يمكنك تلخيص المحتوى الأقدم في طلب واحد ووضع الملخص في رسالة النظام. تحوي الفئة أدناه منطق حفظ التاريخ والتقصير حسب العدد، ويمكنك دمجها مباشرة في خدمة الدردشة الخاصة بك.

复制import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.wuxianzhiapi.com/v1",
    api_key=os.environ["WUXIANZHI_API_KEY"],
)

class Chat:
    def __init__(self, system: str, keep_last: int = 20):
        self.system = {"role": "system", "content": system}
        self.history = []          # 只存 user / assistant 消息
        self.keep_last = keep_last

    def say(self, text: str, max_tokens: int = 500) -> str:
        self.history.append({"role": "user", "content": text})
        recent = self.history[-self.keep_last:]
        resp = client.chat.completions.create(
            model="uncensored",
            messages=[self.system] + recent,
            max_tokens=max_tokens,
        )
        reply = resp.choices[0].message.content
        self.history.append({"role": "assistant", "content": reply})
        return reply

bot = Chat("你是一位说话简短的旅行顾问。")
print(bot.say("我想去云南玩五天，有什么建议？"))
print(bot.say("刚才说的第二个地方，适合带老人吗？"))  # 能接上上一轮

التقصير حسب عدد الرسائل كافٍ، لكنه غير دقيق لأن طول كل رسالة يختلف كثيراً. إذا كنت بحاجة إلى تحكم دقيق، يمكنك استخدام usage.prompt_tokens من الاستجابة كمرجع للاستخدام الفعلي: قم بضغط التاريخ بنشاط عندما يقترب من 50,000. إذا كنت تريد تحويل المحادثة إلى منتج مرافق طويل الأمد، يمكنك الاطلاع على أمثلة تصميم السياق في تطبيقات.