DEV Community: Yusuf Khalidd

كيفية اختبار واجهات برمجة تطبيقات راست (Rust API)؟

Yusuf Khalidd — Wed, 13 May 2026 08:49:06 +0000

لغة Rust تمنحك خادم HTTP سريعًا وآمنًا من حيث الأنواع بسرعة، لكنها لا تمنحك دائمًا حلقة تغذية راجعة سريعة لاختبار عقد الـ API. cargo test مهم، لكنه يدور حول الكود لا حول HTTP الفعلي. لاختبار أكواد الحالة، شكل JSON، الرؤوس، JWT، وطلبات الواجهة الأمامية قبل اكتمال المعالج، تحتاج أداة تعمل خارج سلسلة أدوات Rust وتتحدث مع الخادم قيد التشغيل.

جرّب Apidog اليوم

هذا الدليل يوضح سير عمل عملي لاختبار واجهة برمجة تطبيقات Rust داخل Apidog: توصيل Apidog بخادم Axum أو Actix، إنشاء طلبات، التحقق من JSON المُسلسل بواسطة Serde، التعامل مع JWT، إنشاء mocks للواجهة الأمامية، ثم تشغيل كل ذلك في CI. إذا كنت تستخدم Postman أو curl، فستحصل أيضًا على مواصفات OpenAPI، عناوين mock قابلة للمشاركة، وبيئات عمل جماعية. يمكنك قراءة قصة ترحيل Postman لاحقًا؛ هنا نركز على Rust.

ملخص سريع

شغّل خادم Rust محليًا باستخدام cargo run.
أضف http://localhost:3000 كـ baseUrl في بيئة Apidog.
أنشئ طلب GET /healthz كاختبار دخان.
اختبر JSON القادم من Serde باستخدام assertions بعد كل طلب.
خزّن JWT في متغير {{token}} وطبّق Bearer Auth على مستوى المجلد.
استخدم Mock endpoints حتى تعمل الواجهة الأمامية قبل اكتمال المعالج.
احفظ الطلبات كسيناريو اختبار وشغّلها في CI باستخدام apidog-cli.

لماذا تختبر Rust API خارج `cargo test`؟

cargo test ممتاز لاختبارات الوحدة والتكامل داخل Rust، لكنه ليس دائمًا أفضل طبقة لاختبار عقد HTTP العام.

إذا أردت التأكد من أن المعالج يعيد:

Status code صحيحًا
JSON بالشكل المتوقع
Headers صحيحة
رسالة خطأ واضحة عند الإدخال غير الصحيح
سلوكًا ثابتًا أمام الواجهة الأمامية

فستحتاج عادة إلى كتابة اختبارات HTTP داخل Rust أو استخدام curl يدويًا. هذا يعمل، لكنه يصبح مكلفًا مع تغيّر المعالجات.

Apidog يضيف طبقة عقد فوق الخادم قيد التشغيل:

الطلبات محفوظة وقابلة لإعادة التشغيل.
التأكيدات موجودة بجانب الطلب.
الفريق كله يرى نفس العقود.
يمكن تشغيل نفس السيناريو في CI.
يمكن توليد OpenAPI من الطلبات المحفوظة.

الفكرة: اترك cargo test لاختبار كود Rust، واستخدم Apidog لاختبار واجهة HTTP كما يراها العملاء.

الخطوة 1: أضف خادم Rust كبيئة في Apidog

ابدأ بخادم Axum بسيط:

use axum::{routing::get, Router};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let app = Router::new().route("/healthz", get(|| async { "ok" }));

    let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();

    axum::serve(listener, app).await.unwrap();
}

شغّله:

cargo run

في Apidog:

أنشئ مشروعًا جديدًا.
افتح إدارة البيئات.
أضف بيئة باسم Rust Local.

المتغير	القيمة
`baseUrl`	`http://localhost:3000`
`token`	اتركها فارغة الآن
`apiVersion`	`v1`

أضف بيئة ثانية باسم Rust Staging واستخدم عنوان URL التجريبي. بهذه الطريقة يمكنك التبديل بين المحلي والتجريبي بدون تعديل كل طلب يدويًا.

الخطوة 2: أنشئ أول طلب

داخل المشروع، أنشئ مجلدًا باسم Rust API، ثم أضف طلبًا جديدًا:

Method: GET
URL: {{baseUrl}}/healthz

اضغط Send.

النتيجة المتوقعة:

200 OK
ok

احفظ الطلب باسم:

health-check

هذا الطلب هو أبسط اختبار دخان. إذا فشل، لا تكمل بقية الاختبارات قبل إصلاح الاتصال بالخادم.

إذا ظهر خطأ connection refused، تحقق من:

أن الخادم يعمل.
أن المنفذ صحيح.
أن الخادم مربوط بـ 0.0.0.0:3000 وليس فقط 127.0.0.1:3000، خصوصًا إذا كنت تستخدم Docker أو بيئة محلية مختلفة.

الخطوة 3: اختبر طلب واستجابة JSON باستخدام Serde

أضف مسارًا لإنشاء مستخدم:

use axum::{extract::Json, routing::post, Router};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

#[derive(Serialize)]
struct User {
    id: u64,
    name: String,
    email: String,
}

async fn create_user(Json(payload): Json<CreateUser>) -> Json<User> {
    Json(User {
        id: 1,
        name: payload.name,
        email: payload.email,
    })
}

let app = Router::new().route("/users", post(create_user));

في Apidog، أنشئ طلبًا جديدًا:

Method: POST
URL: {{baseUrl}}/users
Body: JSON

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

أرسل الطلب واحفظه باسم:

create-user

أضف assertions في تبويب Tests:

pm.test("Status is 200", () => {
  pm.expect(pm.response.code).to.eql(200);
});

pm.test("Body has id, name, email", () => {
  const body = pm.response.json();

  pm.expect(body).to.have.property("id");
  pm.expect(body.name).to.eql("Ada Lovelace");
  pm.expect(body.email).to.match(/^[^@]+@[^@]+$/);
});

الآن إذا تغيّر شكل الاستجابة لاحقًا بسبب serde، مثل إضافة:

#[serde(rename_all = "camelCase")]

فسيفشل اختبار العقد قبل أن يصل التغيير إلى الإنتاج.

الخطوة 4: غطِّ حالات رفض Serde

لا تختبر المسار السعيد فقط. اختبر المدخلات الخاطئة أيضًا.

أنشئ الطلبات التالية في Apidog:

الطلب	Body	المتوقع
`create-user-missing-email`	`{ "name": "Ada" }`	`422`، مع رسالة عن الحقل المفقود
`create-user-extra-field`	`{ "name": "Ada", "email": "a@b.c", "admin": true }`	`200` إذا لم تستخدم `deny_unknown_fields`، أو `422` إذا استخدمته
`create-user-wrong-type`	`{ "name": 1, "email": "a@b.c" }`	`422`، مع رسالة عن النوع غير الصحيح

مثال assertion:

pm.test("Status is 422", () => {
  pm.expect(pm.response.code).to.eql(422);
});

هذه الاختبارات توثق سياسة التحقق الفعلية. إذا قررت لاحقًا إضافة:

#[serde(deny_unknown_fields)]

فسيتغير سلوك extra-field، وسيظهر ذلك فورًا في Apidog وCI.

الخطوة 5: اختبر المسارات المحمية بواسطة JWT

غالبًا ما تكون واجهات Rust الإنتاجية محمية بطبقة مصادقة. مثال مبسط باستخدام JWT:

use axum::{Json, http::StatusCode};
use axum_extra::extract::cookie::PrivateCookieJar;
use jsonwebtoken::{decode, DecodingKey, Validation};

async fn me(jar: PrivateCookieJar) -> Result<Json<User>, StatusCode> {
    let token = jar
        .get("token")
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let claims = decode::<Claims>(
        token.value(),
        &DecodingKey::from_secret(b"secret"),
        &Validation::default(),
    )
    .map_err(|_| StatusCode::UNAUTHORIZED)?;

    Ok(Json(User {
        id: claims.claims.sub,
        name: "Ada".into(),
        email: "ada@example.com".into(),
    }))
}

بدل إنشاء JWT يدويًا لكل طلب، أضف Pre-Request Script على مستوى المجلد في Apidog:

const jwt = require("jsonwebtoken");

const token = jwt.sign(
  {
    sub: 1,
    exp: Math.floor(Date.now() / 1000) + 3600
  },
  "secret"
);

pm.environment.set("token", token);

ثم من إعدادات المجلد:

Auth Type: Bearer Token
Token: {{token}}

الآن ترث كل الطلبات داخل المجلد نفس إعداد المصادقة، ويتم توليد JWT جديد قبل التشغيل.

للمزيد حول اختبار JWT، راجع كيفية اختبار مصادقة JWT في واجهات برمجة التطبيقات.

الخطوة 6: اختبر Streaming و Server-Sent Events

يدعم Axum وActix التدفق كجزء أساسي من HTTP. في Axum، يمكن أن يعيد المعالج Sse مبنيًا على futures::Stream.

تنسيق SSE عادة يكون:

data: { ... }

data: { ... }

event: done
data: {}

في Apidog:

أنشئ طلب GET لنقطة SSE.
أرسله.
إذا كان Content-Type هو text/event-stream، ستظهر الاستجابة في وضع streaming.
راقب كل frame مع زمن وصوله.

ما يجب اختباره:

أول event يصل ضمن الزمن المتوقع.
event معين مثل event: done يصل قبل إغلاق الاتصال.
الاتصال لا يبقى مفتوحًا للأبد.
يمكن ضبط timeout للطلب حتى يفشل الاختبار عند التدفق غير المنتهي.

إذا كنت تستخدم WebSocket بدل SSE، استخدم نوع طلب WebSocket في Apidog واحفظ تسلسل الرسائل والاستجابات بنفس الفكرة.

الخطوة 7: أنشئ Mock API لتطوير الواجهة الأمامية بالتوازي

الواجهة الأمامية لا تحتاج انتظار اكتمال كل معالج Rust. يمكنها العمل ضد mock ثابت طالما أن العقد واضح.

في Apidog:

افتح طلب create-user.
اختر Smart Mock.
فعّله.

سيُنشئ Apidog endpoint مثل:

https://mock.apidog.com/m1/<projectId>/users

ويمكن للواجهة الأمامية إرسال POST إليه بنفس شكل الطلب الحقيقي.

لـ mock ديناميكي، استخدم Advanced Mock:

return {
  id: Math.floor(Math.random() * 10000),
  name: body.name,
  email: body.email,
  createdAt: new Date().toISOString()
};

النتيجة: الواجهة الأمامية تحصل على id وcreatedAt واقعيين بدون انتظار معالج Rust.

عندما يصبح المعالج جاهزًا، تغيّر الواجهة الأمامية baseUrl من mock إلى:

http://localhost:3000

ولا تحتاج لتغيير شكل الطلب.

لنفس النمط في بيئات أخرى، راجع بناء واختبار واجهة برمجة تطبيقات Spring Boot وسير عمل اختبار واجهة برمجة التطبيقات العام.

الخطوة 8: احفظ الطلبات كسيناريو CI

حوّل الطلبات إلى سيناريو اختبار قابل للتشغيل بدون واجهة رسومية.

مثال تسلسل:

health-check

تأكيد 200.
create-user

تأكيد 200، ثم خزّن body.id في متغير.
create-user-missing-email

تأكيد 422.
me

يستخدم JWT من Pre-Request Script، ثم يؤكد 200.
طلب SSE

يؤكد أن التدفق يكتمل خلال 5 ثوانٍ.

مثال لتخزين id بعد إنشاء المستخدم:

const body = pm.response.json();

pm.environment.set("userId", body.id);

ثم يمكن استخدامه لاحقًا:

pm.test("Returned id matches created user", () => {
  const body = pm.response.json();

  pm.expect(String(body.id)).to.eql(String(pm.environment.get("userId")));
});

صدّر السيناريو كملف JSON وضعه في المستودع:

tests/apidog/contract.json

مثال GitHub Actions:

- name: Run API contract tests
  run: |
    cargo build --release
    ./target/release/myserver &
    sleep 2
    apidog-cli run tests/apidog/contract.json --env "Rust Local"

الآن كل Pull Request يلمس معالجًا يحصل على اختبار عقد فعلي ضد binary قيد التشغيل.

الخطوة 9: أنشئ OpenAPI من الطلبات المحفوظة

بعد استقرار الطلبات:

افتح قائمة Export في Apidog.
اختر OpenAPI 3.1.
صدّر المواصفة.

ستحصل على ملف مواصفات مبني من الطلبات والأمثلة التي اختبرتها فعليًا.

يمكنك أيضًا تشغيل التصدير من CI:

apidog-cli export --format openapi --output openapi.json

ثم أضف openapi.json إلى المستودع حتى يستخدمه من يحتاج إلى توليد عملاء TypeScript أو Swift أو Kotlin أو Python.

الأسئلة الشائعة

هل يعمل Apidog مع Axum وActix-web؟

نعم. Apidog يتعامل مع HTTP، لذلك يعمل مع Axum وActix-web وRocket وWarp وPoem وLoco. النقطة المهمة في التطوير المحلي هي ربط الخادم بـ 0.0.0.0 عند الحاجة.

كيف أختبر المعالجات التي تتعطل؟

يمكنك وضع CatchPanicLayer من tower-http أمام الـ router لتحويل panic إلى 500. بعدها أنشئ طلبًا في Apidog يؤدي إلى هذا المسار وتأكد من status code.

إذا لم تغلف حالات panic، قد يسقط الاتصال ويظهر خطأ شبكة. هذا أيضًا سلوك عقد يمكن توثيقه.

هل يمكن تشغيل Apidog ضد binary داخل Docker؟

نعم. اجعل baseUrl يشير إلى المنفذ المكشوف للحاوية. إذا كنت تستخدم Docker Compose، تأكد أن مشغل Apidog يستطيع الوصول إلى نفس الشبكة أو استخدم المنفذ المربوط بالمضيف.

ماذا عن gRPC؟

Apidog يدعم نوع طلب gRPC. استورد ملفات .proto، اختر service وmethod، املأ request body، ثم أرسل. نفس مفاهيم البيئات والمصادقة وسيناريوهات الاختبار تنطبق أيضًا.

هل يغني ذلك عن `cargo test`؟

لا. استخدم cargo test لاختبارات منطق Rust الداخلي. استخدم Apidog لاختبار العقد التشغيلي عبر HTTP.

الطبقتان تكملان بعضهما:

cargo test يكتشف دالة مكسورة.
Apidog يكتشف JSON خاطئًا، status code مختلفًا، header مفقودًا، أو سلوك مصادقة غير متوقع.

هل Apidog مجاني لمشاريع Rust مفتوحة المصدر؟

نعم. عميل Apidog مجاني للأفراد والفرق الصغيرة، وتتضمن الطبقة المجانية سيناريوهات الاختبار، المحاكاة، وتصدير OpenAPI.

الخلاصة

واجهات Rust تحتاج اختبارًا لا ينتظر المترجم في كل مرة. باستخدام Apidog يمكنك بناء مجموعة طلبات تتحقق من HTTP الحقيقي، JSON الحقيقي، JWT، mocks للواجهة الأمامية، وسيناريو CI يعمل ضد binary فعلي.

ابدأ بـ GET /healthz، أضف طلبات JSON، غطِّ حالات Serde الفاشلة، ثم شغّل السيناريو في CI. بعد ذلك يصبح كل تغيير في Axum أو Actix اختبار عقد واضحًا بدل مفاجأة في وقت التشغيل.

قم بتنزيل Apidog ووجهه إلى خادم Rust الخاص بك. الإعداد يستغرق دقائق، والنتيجة عقد API مستقل عن cargo وقابل للمشاركة مع الفريق.

حدود معدل استخدام API GPT: المستويات، قيود الاستخدام، وكيفية اختبارها باستخدام Apidog

Yusuf Khalidd — Wed, 13 May 2026 07:09:01 +0000

تقوم بنشر دالة تستدعي واجهة برمجة تطبيقات GPT. تعمل في بيئة الاختبار، ثم تظهر في الإنتاج أخطاء 429 Too Many Requests عند أول موجة مستخدمين. قبل تعديل الكود، تحتاج إلى معرفة الحد الذي اصطدمت به فعليًا: عدد الطلبات في الدقيقة، الرموز في الدقيقة، حد يومي، أو حد مرتبط بالمستوى أو النموذج.

جرّب Apidog اليوم

💡 يوضح هذا الدليل كيفية قراءة حدودك الحالية لأي نموذج GPT من رؤوس الاستجابة، ثم اختبارها عمليًا باستخدام طلبات محفوظة وسيناريو تحميل صغير في Apidog. النتيجة: سير عمل قابل للإعادة كلما ظهرت مشكلة في حدود المعدل.

إذا كنت تستخدم OpenAI في الإنتاج، فتعامل مع حدود المعدل كجزء من تصميم النظام، لا كخطأ طارئ. تختلف حدود GPT-5.5 عن GPT-4.1، وتُحسب نماذج الصور والصوت والتضمينات بطرق مختلفة، وقد يتغير مستوى استخدامك بعد تغييرات الفوترة أو الإنفاق. يوفر Apidog مكانًا واحدًا لإرسال الطلبات، فحص رؤوس الاستجابة، ومحاكاة التزامن قبل نشر التغييرات.

القيود الأربعة التي تحتاج إلى قياسها

تطبق OpenAI عدة حدود على كل مفتاح API. في تطبيق إنتاجي، راقب هذه الأبعاد تحديدًا:

RPM: عدد الطلبات في الدقيقة.
TPM: إجمالي رموز الإدخال والإخراج في الدقيقة.
RPD: عدد الطلبات في اليوم، ويظهر غالبًا في المستويات المجانية أو الأولى.
IPM / TPD / حدود الدفعات: حدود خاصة بنقاط نهاية الصور، الصوت، التضمينات، والـ Batch API.

عند تجاوز الحد، تحصل عادةً على HTTP 429 مع جسم JSON مشابه:

{
  "error": {
    "message": "Rate limit reached for gpt-5.5 in organization org-abc on tokens per min (TPM): Limit 30000, Used 28432, Requested 3120.",
    "type": "tokens",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

لا تتعامل مع 429 كخطأ واحد. اقرأ الحقول التالية أولًا:

type: هل المشكلة في tokens أم requests؟
message: يوضح البعد الذي تم تجاوزه، مثل TPM أو RPM.
code: غالبًا rate_limit_exceeded، لكنه قد يشير أحيانًا إلى مشكلة حصة أو فوترة.

للمرجع العام حول HTTP 429 راجع وثائق MDN 429 ومواصفات RFC 6585. وللسلوك الخاص بـ OpenAI، راجع صفحة حدود المعدل الرسمية.

كيف تعمل المستويات

يقع مفتاح GPT API ضمن مستوى استخدام OpenAI. المستوى يحدد الحدود الفعلية مثل RPM وTPM. الانتقال بين المستويات يعتمد عادةً على:

إجمالي الإنفاق.
مرور مدة معينة منذ أول دفعة.

صورة تقريبية لمستويات نماذج النصوص:

المستوى	عتبة الإنفاق	عتبة الانتظار	طلبات نصية في الدقيقة	رموز نصية في الدقيقة
مجاني	لا يوجد	لا يوجد	3	40k
1	5 دولارات مدفوعة	لا يوجد	500	30k–200k حسب النموذج
2	50 دولارًا مدفوعة	7 أيام	5,000	450k
3	100 دولار مدفوعة	7 أيام	5,000	1M
4	250 دولارًا مدفوعة	14 يومًا	10,000	2M
5	1,000 دولار مدفوعة	30 يومًا	10,000	2M+

هذه الأرقام توضيحية. لا تبنِ تصميم الإنتاج عليها مباشرة. اقرأ الحدود الحالية من لوحة التحكم أو من رؤوس الاستجابة قبل تقدير السعة.

تبعات عملية مهمة:

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

للمقارنة مع موفري نماذج آخرين، راجع شرح حدود معدل استخدام OpenAI API، ودليل حدود معدل استخدام Claude API، ودليل حدود معدل استخدام Grok-3 API.

اقرأ حدودك الحالية من رؤوس الاستجابة

كل استجابة من واجهة GPT API تحتوي غالبًا على رؤوس تحدد الحدود الحالية. راقب هذه الرؤوس:

x-ratelimit-limit-requests: حد الطلبات.
x-ratelimit-remaining-requests: الطلبات المتبقية في النافذة الحالية.
x-ratelimit-limit-tokens: حد الرموز.
x-ratelimit-remaining-tokens: الرموز المتبقية.
x-ratelimit-reset-requests: متى تتم إعادة تعبئة حاوية الطلبات.
x-ratelimit-reset-tokens: متى تتم إعادة تعبئة حاوية الرموز.

مثال قيم قد تراها:

x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 499
x-ratelimit-limit-tokens: 30000
x-ratelimit-remaining-tokens: 29840
x-ratelimit-reset-requests: 6s
x-ratelimit-reset-tokens: 1m30s

هذه القيم هي المصدر العملي للحقيقة عند اختبار نموذج أو مفتاح أو منظمة.

الخطوة 1: إنشاء طلب GPT في Apidog

افتح Apidog، أنشئ مشروعًا جديدًا، ثم أضف طلبًا جديدًا.

استخدم:

POST https://api.openai.com/v1/chat/completions

في تبويب Headers أضف:

المفتاح	القيمة
`Authorization`	`Bearer {{OPENAI_API_KEY}}`
`Content-Type`	`application/json`

استخدم متغير البيئة {{OPENAI_API_KEY}} بدل لصق المفتاح داخل الطلب. بهذه الطريقة يمكنك التبديل بين مفاتيح شخصية، مفاتيح فريق، أو بيئات مختلفة دون تعديل الطلب نفسه.

في تبويب Body اختر JSON واستخدم طلبًا صغيرًا:

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ],
  "max_tokens": 10
}

اضغط Send، ثم افتح تبويب Headers في الاستجابة وابحث عن:

x-ratelimit-limit-requests
x-ratelimit-remaining-requests
x-ratelimit-limit-tokens
x-ratelimit-remaining-tokens

احفظ هذه القيم. ستستخدمها كأساس في اختبارات التحميل التالية.

إذا أردت إعدادًا أوسع يتضمن المصادقة، التدفق، واستدعاءات الأدوات، راجع دليل اختبار ChatGPT API باستخدام Apidog.

الخطوة 2: تأكيد حد RPM بانفجار طلبات صغير

قراءة الرؤوس تخبرك بالحد النظري. لاختبار السلوك عند الاقتراب من الحد، شغّل انفجارًا صغيرًا من الطلبات.

في Apidog:

افتح الطلب المحفوظ.
افتح القائمة بجوار Send.
اختر Run in Test Scenario.
اضبط السيناريو مثلًا على:

الإعداد	القيمة
Iterations	50
Concurrency	10
Delay between iterations	0ms

استخدم طلبًا صغيرًا مثل ping حتى يكون الاختبار أقرب إلى اختبار RPM وليس TPM.

النتائج المحتملة:

ظهور 429 أثناء الاختبار

هذا يؤكد أن حد الطلبات يبدأ عند النقطة التي تشير إليها الرؤوس.
نجاح كل الطلبات

قد يكون حد RPM أعلى مما توقعت. راجع رؤوس الاستجابة للحصول على القيمة الفعلية.

بعد التشغيل، رتّب النتائج حسب رمز الحالة وافتح أي استجابة 429. اقرأ message لمعرفة هل السبب requests per min أم شيء آخر.

للتعامل مع أخطاء 429 بعد ظهورها، راجع دليل تجاوز حد المعدل.

الخطوة 3: افصل RPM عن TPM

اختبار الانفجار السابق يستخدم طلبات صغيرة، لذلك يقيس غالبًا حد RPM. لاختبار TPM، استخدم طلبات أقل ولكن بحمولة نصية أكبر.

عدّل الجسم مثلًا:

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "<3,000 tokens of context here>"
    },
    {
      "role": "user",
      "content": "Summarise the above in one sentence."
    }
  ],
  "max_tokens": 200
}

ثم شغّل سيناريو أخف:

الإعداد	القيمة
Iterations	20
Concurrency	5
Delay between iterations	0ms

إذا كان حد TPM منخفضًا، سترى أخطاء 429 بسبب الرموز قبل الوصول إلى حد الطلبات.

قاعدة القرار:

إذا ظهرت المشكلة بسبب RPM: قلل التزامن، أضف طابورًا، أو وزّع الطلبات زمنيًا.
إذا ظهرت المشكلة بسبب TPM: قلل حجم الموجه، قص السياق، استخدم التخزين المؤقت عند الإمكان، أو قسّم الطلب إلى مراحل أصغر.

الخطوة 4: محاكاة مستخدمين متزامنين

اختبار الانفجار جيد لتأكيد الحد، لكنه لا يشبه الإنتاج دائمًا. في الإنتاج لديك:

مستخدمون متزامنون.
أحجام طلبات مختلفة.
انفجارات قصيرة فوق حمل ثابت.
موجهات قصيرة وطويلة حسب الحالة.

في Apidog، أنشئ سيناريو اختبار يتناوب بين عدة نسخ من الطلب:

طلب صغير.
طلب متوسط.
طلب كبير.

يمكنك استخدام سكربتات JavaScript قبل وبعد الطلب من أجل:

اختيار طول رسالة عشوائي لكل تكرار.
قراءة x-ratelimit-remaining-tokens بعد كل استجابة.
إيقاف السيناريو إذا انخفضت الرموز المتبقية تحت عتبة محددة.
تسجيل زمن الاستجابة للاستجابات 200 منفصلًا عن 429.

مثال منطق بسيط بعد الاستجابة:

const remainingTokens = Number(response.headers.get("x-ratelimit-remaining-tokens"));

if (!Number.isNaN(remainingTokens) && remainingTokens < 1000) {
  console.log("Remaining tokens are below threshold:", remainingTokens);
}

بعد انتهاء السيناريو، استخدم تقرير رموز الحالة لمعرفة:

متى بدأت 429.
هل المشكلة مرتبطة بالطلبات أم الرموز.
هل p95 latency يتدهور قبل ظهور التقييد.

احفظ هذا السيناريو داخل مشروع الفريق. عند ظهور مشكلة لاحقًا، أعد تشغيله وقارن النتائج بدل التخمين.

ماذا تفعل عند ظهور 429

بعد تحديد الحد الذي اصطدمت به، طبّق العلاج المناسب.

1. استخدم التراجع وإعادة المحاولة

عند ظهور 429، لا تعِد المحاولة فورًا. اقرأ رؤوس إعادة التعيين واستخدمها لتحديد الانتظار.

مثال Python مبسط:

import time
import requests

def call_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)

        if response.status_code != 429:
            return response

        reset_tokens = response.headers.get("x-ratelimit-reset-tokens")
        reset_requests = response.headers.get("x-ratelimit-reset-requests")

        # fallback بسيط إذا لم تتمكن من تحويل قيمة الرأس
        delay = min(2 ** attempt, 30)

        print(f"Rate limited. Retry in {delay}s. reset_tokens={reset_tokens}, reset_requests={reset_requests}")
        time.sleep(delay)

    return response

استخدام 2 ** attempt أفضل من إعادة المحاولة الفورية، لكن الأفضل هو الاعتماد على x-ratelimit-reset-* عندما تستطيع تحويله إلى مدة قابلة للاستخدام.

2. ضع الطلبات في قائمة انتظار

إذا كانت حركة المرور متقطعة، ضع الطلبات في queue وصرّفها بمعدل أقل من الحد الأقصى.

النمط العملي:

اضبط حدًا داخليًا أقل من حد OpenAI الحقيقي.
استخدم عامل أمان مثل 70% أو 80% من الحد.
افصل بين محدد RPM ومحدد TPM.

مثال شبه منطقي:

allowed_rpm = openai_rpm_limit * 0.8
allowed_tpm = openai_tpm_limit * 0.8

قبل إرسال أي طلب:
  - تحقق من عدد الطلبات المستخدمة في آخر دقيقة
  - تحقق من عدد الرموز المتوقع استخدامها
  - إذا تجاوزت الحد الداخلي، انتظر أو أدخل الطلب في queue

للتعمق في أنماط التنفيذ، راجع كيفية تنفيذ تحديد معدل واجهة برمجة التطبيقات وتنفيذ تحديد المعدل في واجهات برمجة التطبيقات.

3. استخدم Batch API للأعمال غير المتزامنة

إذا كان عبء العمل لا يحتاج استجابة فورية، مثل:

إثراء بيانات ليلية.
تصنيف مستندات.
إعادة بناء تضمينات.
معالجة ملفات كبيرة.

فانقله إلى Batch API بدل استهلاك حصتك المتزامنة الخاصة بتجربة المستخدم.

للتفريق بين التقييد وتحديد المعدل، راجع التقييد مقابل تحديد المعدل.

أخطاء GPT 429 الشائعة

`Rate limit reached ... on requests per min (RPM)`

المشكلة: عدد الاستدعاءات في الدقيقة كبير جدًا.

الحلول:

قلل التزامن.
لا تستخدم map متوازية على كل السجلات دفعة واحدة.
استخدم worker pool بحجم محسوب.
أضف queue أمام استدعاءات GPT.

قاعدة بسيطة:

max_workers = floor(RPM / 2)

استخدم عامل أمان، خصوصًا إذا كانت هناك خدمات أخرى تشارك نفس المنظمة أو المفتاح.

`Rate limit reached ... on tokens per min (TPM)`

المشكلة: الطلبات تستهلك رموزًا كثيرة.

الحلول:

قلل طول system prompt.
لا ترسل مستندات كاملة داخل السياق دون تقطيع.
قلل max_tokens.
اختصر نتائج RAG.
خزّن الأجزاء الثابتة عند توفر آلية مناسبة.
قسّم الطلب الكبير إلى طلبات أصغر إذا كان ذلك مناسبًا.

`You exceeded your current quota, please check your plan and billing details`

هذا يبدو مثل 429، لكنه غالبًا ليس مشكلة rate limit تشغيلية. تحقق من:

حد الإنفاق الشهري.
بطاقة الدفع.
الرصيد المدفوع مسبقًا.
حالة الفوترة.

الحل هنا في لوحة الفوترة، وليس في إعادة المحاولة أو تقليل التزامن.

قائمة تحقق سريعة قبل نشر ميزة تستخدم GPT

استخدم هذه القائمة قبل الإطلاق:

[ ] أرسلت طلبًا واحدًا لكل نموذج مستخدم وقرأت رؤوس x-ratelimit-*.
[ ] خزّنت قيم RPM وTPM الحالية في وثائق الفريق.
[ ] شغّلت اختبار RPM بطلب صغير.
[ ] شغّلت اختبار TPM بطلب كبير.
[ ] أضفت retry مع backoff.
[ ] أضفت queue أو limiter إذا كانت الحركة متقطعة.
[ ] قللت max_tokens إلى سقف واقعي.
[ ] عزلت مفاتيح الإنتاج عن مفاتيح الاختبار عند الحاجة.
[ ] حفظت سيناريو Apidog في مشروع مشترك للفريق.

الأسئلة الشائعة

هل يكلف Apidog أي شيء لاختبار حدود معدل GPT؟

لا للاختبارات الأساسية. تغطي الخطة المجانية اختبار الطلبات الفردية وتشغيل اختبارات متزامنة صغيرة. تحتاج إلى خطة مدفوعة إذا أردت أحمالًا أكبر، مساحات عمل جماعية، أو تشغيلات مجدولة. راجع تسعير Apidog.

هل يمكنني اختبار حدود المعدل دون استهلاك رموز حقيقية؟

جزئيًا. أرخص فحص هو طلب صغير جدًا مع max_tokens: 1. ستستهلك رموزًا قليلة وتعود الرؤوس كاملة. لاختبار منطق إعادة المحاولة دون استدعاء OpenAI، استخدم خادمًا وهميًا في Apidog يحاكي استجابة 429.

لماذا يبدو مفتاحي من المستوى الأول أبطأ من مفتاح زميل في المستوى نفسه؟

لأن الحدود غالبًا على مستوى المنظمة، لا المفتاح فقط. إذا كان مفتاحك داخل منظمة مشتركة مع استخدام كثيف، فأنت تشارك نفس الحصة. شغّل نفس الطلب من المفتاحين وقارن x-ratelimit-remaining-tokens.

كيف أعرف حد كل نموذج؟

أرسل طلبًا رخيصًا لكل نموذج واقرأ رؤوس الاستجابة. لا تعتمد على جداول عامة فقط. قد تختلف حدود نموذجين قريبين في الاسم أو في إصدار اللقطة، مثل gpt-5.5 وgpt-5.5-0901.

هل تُحتسب طلبات البث بشكل مختلف؟

نعم بالنسبة إلى TPM. قد يحجز طلب البث رموزًا بناءً على max_tokens، حتى لو كان الإكمال الفعلي أقصر. اجعل max_tokens قريبًا من الحد الواقعي. يغطي دليل اختبار ChatGPT API باستخدام Apidog هذا السلوك بمزيد من التفصيل.

هل يمكنني مشاركة اختبار حد المعدل مع فريقي؟

نعم. احفظ الطلب وسيناريو الاختبار في مشروع Apidog مشترك. يمكن لكل عضو تشغيل الاختبار بمفتاحه عبر تبديل البيئة، مما يجعل تشخيص "هل المشكلة في مفتاحي أم في المفتاح العام؟" أسرع بكثير.

GPT-5.5 Pro ضد Instant: متى يكون دفع 6 أضعاف التكلفة مستحقًا؟

Yusuf Khalidd — Tue, 12 May 2026 06:56:00 +0000

تقدم OpenAI نوعين من GPT-5.5: إصدار Instant بسعر 5 دولارات للمدخلات و30 دولارًا للمخرجات لكل مليون رمز، وإصدار Pro بسعر 30 دولارًا للمدخلات و180 دولارًا للمخرجات. هذا يعني علاوة ثابتة قدرها 6 أضعاف. القرار الهندسي العملي هو: متى تستحق هذه العلاوة، ومتى تكون إنفاقًا زائدًا بلا عائد؟

جرّب Apidog اليوم

سيركز هذا الدليل على طريقة تنفيذية لاتخاذ القرار: حساب التكلفة على أعباء عمل واقعية، مقارنة الدقة حسب نوع المهمة، تقدير تكلفة الكمون، وبناء مجموعة اختبار في Apidog يمكنك استخدامها لمقارنة Instant وPro على طلباتك الفعلية.

خلاصة القول (TL;DR)

استخدم GPT-5.5 Instant كخيار افتراضي للدردشة، التلخيص، التصنيف، QA، واستدعاء الأدوات الواضحة. انتقل إلى Pro فقط عندما تكون تكلفة الإجابة الخاطئة أعلى من علاوة الرموز البالغة 6 أضعاف للمحادثة الكاملة.

أمثلة مناسبة لـ Pro:

صياغة أو مراجعة العقود القانونية
الفرز الطبي أو التلخيص السريري عالي المخاطر
تحليل المستندات المالية
تخطيط الوكلاء متعدد الخطوات
إعادة هيكلة كود عبر عدة ملفات

إذا لم تستطع تحديد تكلفة الخطأ بالدولار لميزة معينة، فابدأ بـ Instant وقِس قبل الترقية إلى Pro.

مقدمة

التسعير الجديد يجعل قرار اختيار النموذج قابلًا للنمذجة بدل الاعتماد على الانطباع. على سبيل المثال، فريق يعالج 100,000 رسالة دعم يوميًا قد يدفع 4,500 دولار شهريًا على Instant أو 27,000 دولار شهريًا على Pro لنفس الحجم. الفرق الشهري 22,500 دولار لميزة واحدة، ويجب تبريره برقم واضح.

سنغطي:

كيف تحسب تكلفة Instant وPro لكل ميزة.
أين يظهر فارق الدقة فعليًا.
كيف تقيس الكمون والتكلفة على طلباتك.
كيف تبني مجموعة اختبار في Apidog قبل اعتماد القرار في الإنتاج.

إذا كنت جديدًا على عائلة 5.5، فابدأ من دليل الوصول وواجهة برمجة التطبيقات لـ GPT-5.5 Instant، ثم راجع دليل تتبع إنفاق واجهة برمجة تطبيقات OpenAI لربط التكلفة بالميزات. ولتفاصيل المعلمات والبث والمخرجات المنظمة، راجع شرح مرجع واجهة برمجة تطبيقات GPT-5.5.

النموذجان وراء عائلة GPT-5.5

يتشارك Instant وPro نفس واجهة API ونفس شكل الطلب. الاختلاف العملي يظهر في:

معرف النموذج
ميزانية التفكير الافتراضية
السعر لكل رمز
الكمون المتوقع

معرفات النماذج:

Instant: gpt-5.5
Pro: gpt-5.5-pro

يدعم كلاهما:

سياق إدخال حتى 272,000 رمز
مخرجات حتى 128,000 رمز
نفس قيم reasoning_effort: minimal, low, medium, high
البث عبر واجهة Responses API
نفس شكل الطلب تقريبًا

هذا يعني أنك تستطيع تبديل النموذج من طبقة توجيه واحدة دون إعادة كتابة تكامل API.

مقارنة الأسعار

النموذج	إدخال / مليون رمز	إخراج / مليون رمز
GPT-5.5 Instant	5$	30$
GPT-5.5 Pro	30$	180$

Batch يخفض التكلفة إلى النصف:

النموذج	إدخال Batch	إخراج Batch
Instant	2.50$	15$
Pro	15$	90$

والتخزين المؤقت للطلبات يخفض رموز الإدخال المخزنة مؤقتًا إلى:

Instant: 0.50$ لكل مليون رمز
Pro: 3$ لكل مليون رمز

إذا كان عبء العمل غير فوري، استخدم Batch. وإذا كان لديك system prompt ثابت، فعّل التخزين المؤقت.

مقارنة الكمون

Instant عند:

reasoning_effort = minimal

قد يعيد الرمز الأول خلال 200 إلى 400 مللي ثانية للطلبات القصيرة.

Pro عند:

reasoning_effort = high

قد يستغرق 8 إلى 30 ثانية قبل أول رمز، لأنه ينفذ تفكيرًا داخليًا أطول قبل الصياغة. أشارت TechCrunch إلى هذا الفارق في ملاحظات إصدار GPT-5.5 Pro.

القاعدة العملية:

واجهات الدردشة التفاعلية: ابدأ بـ Instant.
المعالجة غير المتزامنة أو عالية المخاطر: قيّم Pro.
لا تفصل اختيار النموذج عن reasoning_effort.

فارق الدقة: أين يتفوق إصدار Pro؟

حسب الأرقام المنشورة من OpenAI، يتفوق Pro في المهام متعددة الخطوات حيث تتراكم الأخطاء، بينما يتقارب مع Instant في المهام الفردية مثل الاسترجاع، التنسيق، والتلخيص البسيط.

أمثلة منشورة:

GPQA Diamond: Pro حوالي 87% مقابل 71% لـ Instant.
SWE-bench Verified: Pro حوالي 78% مقابل 61% لـ Instant.
MMLU وHellaSwag: كلاهما في التسعينات العليا، والفارق صغير.
في طلبات طبية وقانونية عدائية، يقلل Pro الإجابات الخاطئة الواثقة بنحو 40% مقارنة بـ Instant وفق مقياس داخلي منشور.

متى تختار Pro؟

استخدم Pro عندما يحتاج النموذج إلى الاحتفاظ بعدة قيود في الذاكرة العاملة أثناء التفكير، مثل:

مراجعة عقد كامل
تحليل مخاطر قانونية
تشخيص تفريقي
تخطيط وكيل متعدد الخطوات
إصلاح كود عبر عدة ملفات

متى يكفي Instant؟

Instant مناسب غالبًا لـ:

دعم العملاء
استرداد إجابات FAQ
تلخيص محتوى منخفض المخاطر
تصنيف المشاعر
توجيه النية
استدعاء أدوات محددة جيدًا
إكمال كود داخل ملف واحد

اختبار سريع للمقارنة بين Instant وPro

استخدم نفس الطلب وقارن النموذجين. شكل API واحد، والاختلاف في model وreasoning.effort.

from openai import OpenAI

client = OpenAI()

prompt = """Analyze this contract clause for unilateral termination risk:
'Either party may terminate this agreement for convenience upon
thirty (30) days written notice, provided that the terminating party
shall pay any amounts then due.'"""

instant = client.responses.create(
    model="gpt-5.5",
    reasoning={"effort": "minimal"},
    input=prompt,
)

pro = client.responses.create(
    model="gpt-5.5-pro",
    reasoning={"effort": "high"},
    input=prompt,
)

print("INSTANT:", instant.output_text)
print("PRO:", pro.output_text)

في اختبار كهذا، قد يعطي Instant إجابة قصيرة وسريعة تشير إلى حق الإنهاء الأساسي. بينما قد يعطي Pro تحليلًا أطول يشمل المخاطر، ثغرات تعريف “المبالغ المستحقة”، وتعديلات تعاقدية مقترحة. الاختلاف هنا ليس في شكل API، بل في عمق التحليل والتكلفة والكمون.

بناء تقييم محلي على طلباتك

لا تعتمد على المعايير العامة فقط. شغّل النموذجين على 50 إلى 200 طلب من حركة المرور الحقيقية أو القريبة منها.

import time, csv
from openai import OpenAI

client = OpenAI()

PROMPTS = open("eval_prompts.txt").read().split("\n---\n")

CONFIGS = [
    ("gpt-5.5", "minimal"),
    ("gpt-5.5", "high"),
    ("gpt-5.5-pro", "minimal"),
    ("gpt-5.5-pro", "high"),
]

with open("results.csv", "w") as f:
    w = csv.writer(f)
    w.writerow([
        "model",
        "effort",
        "prompt_id",
        "latency_s",
        "in_tokens",
        "out_tokens",
        "cost_usd",
        "output"
    ])

    for i, p in enumerate(PROMPTS):
        for model, effort in CONFIGS:
            t0 = time.time()

            r = client.responses.create(
                model=model,
                reasoning={"effort": effort},
                input=p,
            )

            latency = time.time() - t0

            input_tokens = r.usage.input_tokens
            output_tokens = r.usage.output_tokens

            rate_in = 5 if model == "gpt-5.5" else 30
            rate_out = 30 if model == "gpt-5.5" else 180

            cost = (
                input_tokens * rate_in +
                output_tokens * rate_out
            ) / 1_000_000

            w.writerow([
                model,
                effort,
                i,
                round(latency, 2),
                input_tokens,
                output_tokens,
                round(cost, 5),
                r.output_text[:500]
            ])

بعد التشغيل:

قيّم المخرجات بشكل أعمى.
احسب الدقة لكل نموذج.
احسب التكلفة لكل طلب.
احسب الكمون.
قرر لكل ميزة، لا لكل منتج كامل.

لإعداد سير عمل تقييم API للوكلاء، راجع دليل اختبار واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي. ولتوليد حالات اختبار من آثار الإنتاج، راجع توليد الاختبارات المدعوم بالذكاء الاصطناعي.

حساب التكلفة: متى تكون 6 أضعاف مستحقة؟

الميزة 1: روبوت دعم العملاء

الحجم:

100,000 رسالة يوميًا
متوسط الطلب: 800 رمز
متوسط الاستجابة: 250 رمز

الاستهلاك اليومي:

80 مليون رمز إدخال
25 مليون رمز إخراج

تكلفة Instant:

80M * 5$ / 1M = 400$
25M * 30$ / 1M = 750$

الإجمالي اليومي = 1,150$
الإجمالي الشهري ≈ 34,500$

تكلفة Pro:

80M * 30$ / 1M = 2,400$
25M * 180$ / 1M = 4,500$

الإجمالي اليومي = 6,900$
الإجمالي الشهري ≈ 207,000$

العلاوة الشهرية:

207,000$ - 34,500$ = 172,500$

الحكم: استخدم Instant. غالبًا ستحصل على عائد أعلى من تحسين الاسترجاع وsystem prompt بدل دفع علاوة Pro.

الميزة 2: مساعد مراجعة الكود

الحجم:

5,000 تعليق مراجعة يوميًا
متوسط الطلب: 8,000 رمز
متوسط الاستجابة: 1,200 رمز

الاستهلاك اليومي:

40 مليون رمز إدخال
6 مليون رمز إخراج

Instant:

40M * 5$ = 200$
6M * 30$ = 180$

الإجمالي اليومي = 380$
الإجمالي الشهري ≈ 11,400$

Pro:

40M * 30$ = 1,200$
6M * 180$ = 1,080$

الإجمالي اليومي = 2,280$
الإجمالي الشهري ≈ 68,400$

العلاوة الشهرية:

68,400$ - 11,400$ = 57,000$

إذا اكتشف Pro خمسة أخطاء حقيقية إضافية لكل 1,000 مراجعة، وكل خطأ يوفر ساعة مهندس كبير بسعر 150$، فالقيمة اليومية تكون:

5 أخطاء * 5 مجموعات من 1000 مراجعة = 25 خطأ يوميًا
25 * 150$ = 3,750$ يوميًا
≈ 112,500$ شهريًا

في هذه الحالة، قد يستحق Pro. لكن القرار يعتمد على قياس معدل اكتشاف الأخطاء، لا على الافتراض.

الميزة 3: ملخصات قانونية

الحجم:

500 وثيقة يوميًا
متوسط الطلب: 40,000 رمز
متوسط الاستجابة: 3,000 رمز

الاستهلاك اليومي:

20 مليون رمز إدخال
1.5 مليون رمز إخراج

Instant:

20M * 5$ = 100$
1.5M * 30$ = 45$

الإجمالي اليومي = 145$
الإجمالي الشهري ≈ 4,350$

Pro:

20M * 30$ = 600$
1.5M * 180$ = 270$

الإجمالي اليومي = 870$
الإجمالي الشهري ≈ 26,100$

العلاوة الشهرية:

26,100$ - 4,350$ = 21,750$

في العقود القانونية، بند تعويض مفقود قد يكلف أكثر من علاوة Pro السنوية. الحكم: استخدم Pro، وإذا لم تكن النتائج فورية فاستخدم Batch لتخفيض التكلفة إلى النصف.

قاعدة التعادل العملية

استخدم هذه القاعدة:

اختر Pro عندما تكون القيمة المتوقعة للأخطاء التي يمنعها
أكبر من علاوة التكلفة مقارنة بـ Instant.

صيغة مبسطة:

قيمة التحسن = عدد الطلبات * فرق الدقة * تكلفة الخطأ

إذا كانت:

قيمة التحسن > تكلفة Pro الإضافية

فاستخدام Pro مبرر.

مثال:

100,000 طلب شهريًا
فرق الدقة = 1%
تكلفة الخطأ = 50$

قيمة التحسن = 100,000 * 0.01 * 50
= 50,000$

إذا كانت علاوة Pro أقل من 50,000$ شهريًا، فهو خيار منطقي. إذا كانت أعلى، ابقَ على Instant أو استخدم التصعيد الانتقائي.

اختبر المفاضلة بين Pro وInstant باستخدام Apidog

لا تنقل قرار النموذج إلى الإنتاج بناءً على معيار عام. أنشئ مجموعة اختبار تراجع صغيرة في Apidog وشغّلها عند كل تغيير في prompt أو نموذج.

1. أنشئ مشروعًا جديدًا

افتح Apidog وأنشئ مشروعًا لاختبارات GPT-5.5.

2. أضف طلبين إلى Responses API

Endpoint:

POST https://api.openai.com/v1/responses

الرؤوس:

Authorization: Bearer {{OPENAI_KEY}}
Content-Type: application/json

اجعل OPENAI_KEY متغير بيئة بدل لصقه داخل الطلب.

3. طلب Instant

{
  "model": "gpt-5.5",
  "reasoning": {
    "effort": "minimal"
  },
  "input": "{{prompt}}"
}

سمّه مثلًا:

gpt55-instant-minimal

4. طلب Pro

{
  "model": "gpt-5.5-pro",
  "reasoning": {
    "effort": "high"
  },
  "input": "{{prompt}}"
}

سمّه:

gpt55-pro-high

5. اربط `{{prompt}}` بملف بيانات

استخدم ملفًا يحتوي على 50 إلى 200 طلب اختبار. كل صف يمثل prompt واحدًا.

6. التقط المقاييس

أضف اختبارات أو post-processing لتسجيل:

response.usage.input_tokens
response.usage.output_tokens
زمن الاستجابة
نص الاستجابة
حالة نجاح مخطط الإخراج إذا كنت تستخدم JSON schema

7. قارن النتائج

شغّل الطلبين كدفعة واحدة على نفس البيانات. استخدم عرض الفروقات في Apidog لمقارنة الردود جنبًا إلى جنب، ثم صدّر النتائج إلى CSV واحسب التكلفة لكل طلب.

احتفظ بهذه المجموعة كاختبار تراجع. عند تغيير prompt أو إصدار نموذج جديد، أعد التشغيل وقارن النتائج. يمكنك استخدام مساحة عمل Apidog للاحتفاظ بالسجل، أو تنزيل Apidog لإعداد سير العمل محليًا. ولشرح أكثر تفصيلًا، راجع سير عمل اختبار واجهة البرمجة لمهندسي ضمان الجودة.

تقنيات عملية لتقليل التكلفة

1. وجّه حسب الميزة، لا حسب المستخدم

لا تجعل قاعدة مثل “كل مستخدم مدفوع يحصل على Pro”. الأفضل:

feature = legal_summary  -> Pro
feature = support_chat   -> Instant
feature = code_review    -> Instant ثم تصعيد عند الحاجة

أضف وسمًا لكل استدعاء API:

{
  "feature": "code_review",
  "risk_class": "medium",
  "model_policy": "escalate_on_failure"
}

2. استخدم Pro كمسار تصعيد

نمط عملي:

أرسل الطلب إلى Instant.
تحقق من النتيجة:
- هل فشل JSON schema؟
- هل الثقة منخفضة؟
- هل استدعاء الأداة غير صالح؟
- هل المهمة عالية المخاطر؟
إذا فشل التحقق، أعد الطلب إلى Pro.

بهذا تدفع تكلفة Pro فقط على 5% إلى 15% من الطلبات بدل 100%.

3. فعّل التخزين المؤقت للطلبات

إذا كان system prompt ثابتًا وطويلًا، فتأكد من أن البادئة لا تتغير حرفيًا بين الطلبات. راقب:

response.usage.cached_tokens

وانشئ تنبيهًا إذا انخفض معدل cache hit.

4. استخدم Batch للمهام غير الفورية

استخدم Batch لأي مهمة لا تحتاج نتيجة فورية، مثل:

توليد محتوى ليلي
تلخيص أسبوعي
تصنيف بأثر رجعي
معالجة مستندات كبيرة

Batch يعطي نفس النموذج ونفس نوع النتائج بنصف السعر، مقابل وقت إنجاز أطول.

5. لا تملأ نافذة السياق بلا داعٍ

يدعم كلا النموذجين حتى 272,000 رمز إدخال، لكن التكلفة تزيد خطيًا. وبعد حوالي 180,000 رمز، قد تتدهور جودة الاسترجاع في المهام الطويلة. الأفضل:

تقسيم المستندات
استخدام retrieval
تمرير المقاطع ذات الصلة فقط
تلخيص السياق قبل الطلب النهائي

أخطاء شائعة

اختيار النموذج داخل كود العميل بدل طبقة توجيه مركزية.
مقارنة النماذج على benchmarks فقط، لا على طلباتك.
استخدام reasoning_effort=high دائمًا مع Pro.
نسيان max_output_tokens.
عدم مراقبة cached_tokens.
استخدام Pro لكل مستخدم مدفوع بدل استخدامه للمهام عالية المخاطر فقط.
تجاهل الكمون في واجهات المستخدم التفاعلية.

مثال على حد آمن للمخرجات:

r = client.responses.create(
    model="gpt-5.5-pro",
    reasoning={"effort": "high"},
    input=prompt,
    max_output_tokens=1200,
)

لاختيار نماذج أخرى عبر العائلات، راجع دليل واجهة برمجة تطبيقات Gemini 3 Flash Preview، وخيارات الوصول المجاني إلى واجهة برمجة تطبيقات GPT-5.5.

حالات استخدام واقعية

فرز مطالبات التأمين

النمط:

Instant لملخصات الاستقبال الأولية.
Pro للأسئلة المعقدة المتعلقة بالسياسة.
حوالي 12% من المطالبات تصل إلى Pro.

النتيجة: إنفاق أقل مقارنة باستخدام Pro لكل شيء، مع دقة أعلى في الحالات الصعبة.

مساعد مراجعة الكود

النمط:

Instant لكل Pull Request للتحقق من الأسلوب والأخطاء الواضحة.
Pro عندما يلمس التغيير أكثر من ثلاثة ملفات أو مسارات حساسة.

القرار هنا يعتمد على قياس عدد الأخطاء الإضافية التي يكتشفها Pro مقارنة بتكلفته السنوية.

ملخصات قبول المستشفى

النمط:

Pro مع reasoning_effort=high لكل ملخص عالي المخاطر.
Batch للملخصات غير الفورية.

في هذا النوع من المهام، تكلفة الخطأ أعلى بكثير من تكلفة الرموز، لذلك يكون النقاش حول تقليل التكلفة عبر Batch والتخزين المؤقت، لا حول استخدام Instant بدل Pro.

الخلاصة

العلاوة البالغة 6 أضعاف بين Instant وPro ليست مشكلة بحد ذاتها. هي إشارة تجبرك على حساب قيمة الإجابة الصحيحة.

القاعدة العملية:

اجعل Instant هو الافتراضي.
استخدم Pro فقط عندما تعرف تكلفة الخطأ.
وجّه حسب الميزة، لا حسب المستخدم.
استخدم reasoning_effort كجزء من قرار النموذج.
فعّل التخزين المؤقت وBatch عندما يسمح عبء العمل.
ابنِ مجموعة اختبار تراجع في Apidog قبل تثبيت القرار في الإنتاج.
أعد التقييم مع كل إصدار نموذج أو تغيير أسعار.

للبدء، شغّل مقارنة التكلفة والدقة على طلباتك الخاصة. راجع أيضًا دليل الوصول إلى GPT-5.5 Instant ودليل إسناد إنفاق OpenAI لكل ميزة.

الأسئلة الشائعة

س: هل GPT-5.5 Pro أفضل بـ 6 أضعاف من Instant؟

ج: لا. هو أغلى بـ 6 أضعاف لكل رمز. في بعض المهام عالية المخاطر ومتعددة الخطوات يكون أفضل بوضوح، لكن في كثير من المهام اليومية يكون الفرق غير كافٍ لتبرير التكلفة.

س: هل يمكنني استخدام نفس كود API لكلا النموذجين؟

ج: نعم. غيّر فقط model من gpt-5.5 إلى gpt-5.5-pro. راجع دليل واجهة برمجة تطبيقات GPT-5.5.

س: هل يعمل reasoning_effort بنفس الطريقة على النموذجين؟

ج: يقبل نفس القيم على كليهما، لكن تأثيره أكبر على Pro بسبب قدرة التفكير الأعلى.

س: ما مقدار التوفير من التخزين المؤقت؟

ج: رموز الإدخال المخزنة مؤقتًا تنخفض من 30$ إلى 3$ لكل مليون في Pro، ومن 5$ إلى 0.50$ في Instant.

س: هل أبدأ بـ Pro ثم أخفّض إلى Instant؟

ج: الأفضل العكس: ابدأ بـ Instant وصعّد إلى Pro عند فشل التحقق أو ارتفاع المخاطر.

س: ما عقوبة الكمون في Pro؟

ج: عند reasoning_effort=high قد يستغرق أول رمز 8 إلى 30 ثانية، وقد تصل الاستجابة الكاملة إلى 20 إلى 60 ثانية للردود الطويلة.

س: هل Batch يعطي نفس الإجابات؟

ج: نعم. Batch خصم على وقت التسليم، وليس تبديلًا للنموذج. نفس النموذج ونصف السعر، مع نافذة إنجاز قد تصل إلى 24 ساعة.

س: متى أعيد تقييم القرار؟

ج: عند كل إعلان نموذج جديد، أو تغيير أسعار، أو تعديل كبير في prompt. استخدم مجموعة اختبار تراجع قابلة لإعادة التشغيل مثل الموضحة في سير عمل اختبار واجهة برمجة وكلاء الذكاء الاصطناعي.

التحقق من استجابات API في اختبارات بلاي رايت

Yusuf Khalidd — Tue, 12 May 2026 06:21:48 +0000

تنجح اختبارات Playwright لديك: يتم النقر على زر تسجيل الدخول، تظهر لوحة التحكم، ويرسم الرسم البياني. ثم يبلغ عميل عن خطأ: أرقام الرسم البياني غير صحيحة. عند الفحص تجد أن الـ API أعادت 200 OK مع حمولة مشوهة، لكن اختبار E2E لم يلتقط ذلك لأنه تحقق فقط من ظهور عناصر الواجهة. هذه هي الفجوة التي لا تسدها اختبارات المتصفح وحدها. تحتاج إلى تأكيدات API تتحقق من العقد، المخطط، ودلالات الاستجابة. أدوات مثل Apidog تساعدك على اختبار مواصفات OpenAPI وسيناريوهات API وتشغيلها بجانب Playwright داخل CI.

جرّب Apidog اليوم

ملخص سريع

أفضل نمط عملي هو تشغيل طبقتين من الاختبارات:

Playwright لتدفقات الواجهة، اعتراض الشبكة، وفحوصات API الخفيفة عند حدود إجراء المستخدم.
Apidog للتحقق العميق من مخططات الاستجابة، السيناريوهات المتسلسلة، ومسارات الأخطاء.

اجعل مصدر الحقيقة واحدًا: ملف openapi.yaml أو openapi.json. استخدمه في Playwright لتوليد fixtures وطلبات متوقعة، واستورده في Apidog لبناء السيناريوهات والتأكيدات. بعد ذلك شغّل المجموعتين في CI بحيث يفشل أي تغيير غير متوافق في العقد بسرعة.

لماذا لا تكفي اختبارات Playwright وحدها؟

توثيق Playwright يوضح أن اختبار API ممكن عبر أداة request:

const response = await request.get('/api/orders');
expect(response.status()).toBe(200);

هذا جيد كبداية، لكنه لا يكفي عند التوسع. غالبًا تنتهي بمئات الاختبارات التي تتحقق من status code فقط، بينما تتسرب أخطاء مثل:

تراجع شكل الحمولة

تغير الحقل من total_count إلى totalCount. الواجهة قد تعرض صفرًا أو تحول القيمة ضمنيًا، فيمر اختبار UI.
انحراف منطق العمل

نقطة نهاية الخصم تعيد 10% بدل 15%. الواجهة تعرض ما وصلها، والاختبار ينجح رغم أن النتيجة خاطئة.
ضعف تغطية مسارات الأخطاء

اختبارات Playwright تميل إلى happy path. لكنها لا تغطي عادةً حالات 401، 409، 429، أو الفشل الجزئي.

الحل العملي: لا تجعل Playwright مسؤولًا عن كل شيء. استخدمه للواجهة، واستخدم Apidog لاختبار API كسيناريوهات مستقلة مبنية على نفس OpenAPI spec. إذا أردت تجهيز الأداة أولًا، يمكنك تنزيل Apidog.

للاطلاع على سياق أوسع حول اختيار أدوات اختبار API، راجع أدوات اختبار واجهة برمجة التطبيقات لمهندسي ضمان الجودة.

البنية المقترحة

استخدم هذا التقسيم:

repo/
├─ openapi.yaml
├─ fixtures/
│  └─ order.json
├─ tests/
│  ├─ fixtures/
│  │  └─ api.ts
│  ├─ orders.spec.ts
│  └─ dashboard.spec.ts
└─ apidog/
   └─ scenarios/
      └─ checkout.json

القواعد:

openapi.yaml هو العقد الرسمي.
ملفات fixtures/ هي بيانات الاختبار المشتركة.
Playwright يقرأ fixtures لتنفيذ UI/API smoke checks.
Apidog يستورد نفس OpenAPI ويبني عليها السيناريوهات.
CI يشغّل Playwright و Apidog معًا.

للمزيد حول نهج التصميم أولًا، راجع سير عمل واجهة برمجة التطبيقات القائمة على التصميم أولاً.

إنشاء fixture مشترك في Playwright

ابدأ بملف fixture واحد يجهز APIRequestContext، يجلب token جديدًا، ويحمّل بيانات الطلب من fixtures/order.json.

// tests/fixtures/api.ts
import { test as base, APIRequestContext, expect } from '@playwright/test';
import { readFileSync } from 'fs';
import path from 'path';

type ApiFixtures = {
  apiRequest: APIRequestContext;
  authToken: string;
  sampleOrder: Record<string, unknown>;
};

export const test = base.extend<ApiFixtures>({
  apiRequest: async ({ playwright }, use) => {
    const ctx = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'https://api.staging.example.com',
      extraHTTPHeaders: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
      },
    });

    await use(ctx);
    await ctx.dispose();
  },

  authToken: async ({ apiRequest }, use) => {
    const res = await apiRequest.post('/auth/token', {
      data: {
        email: 'qa@example.com',
        password: process.env.QA_PASSWORD,
      },
    });

    expect(res.status()).toBe(200);

    const body = await res.json();
    await use(body.access_token);
  },

  sampleOrder: async ({}, use) => {
    const raw = readFileSync(
      path.join(__dirname, '..', '..', 'fixtures', 'order.json'),
      'utf8',
    );

    await use(JSON.parse(raw));
  },
});

export { expect };

بعد ذلك، استورد test من هذا الملف بدلًا من @playwright/test:

// tests/orders.spec.ts
import { test, expect } from './fixtures/api';

test('POST /orders returns a valid order with 15 percent discount', async ({
  apiRequest,
  authToken,
  sampleOrder,
}) => {
  const res = await apiRequest.post('/orders', {
    headers: { Authorization: `Bearer ${authToken}` },
    data: { ...sampleOrder, coupon: 'SAVE15' },
  });

  expect(res.status()).toBe(201);

  const body = await res.json();

  expect(body).toMatchObject({
    id: expect.any(String),
    status: 'pending',
    discount_pct: 15,
    total_cents: expect.any(Number),
  });

  expect(body.total_cents).toBeLessThan(
    sampleOrder.subtotal_cents as number,
  );
});

هذا الاختبار لا يكتفي بـ 201. بل يتحقق من دلالة مهمة: discount_pct يجب أن تكون 15.

ربط نفس البيانات داخل Apidog

في Apidog:

افتح المشروع.
اختر Import.
استورد openapi.yaml.
أنشئ سيناريو مثل Checkout.
أضف خطوة POST /orders.
استخدم نفس حمولة fixtures/order.json كـ body أو Data Set.
فعّل JSON Schema validation مقابل مكوّن Order في OpenAPI.
أضف تأكيدًا على discount_pct = 15.

بهذا تحصل على طبقتين:

Playwright يلتقط التأكيد الدلالي المرتبط بتدفق المستخدم.
Apidog يلتقط أي انحراف في المخطط، الحقول المطلوبة، الأنواع، أو enum values.

إذا كنت تستخدم Postman حاليًا وتفكر في الانتقال، راجع بدائل Postman المستضافة ذاتيًا.

إعداد سير عمل Apidog + Playwright

الخطوة 1: اجعل OpenAPI هو العقد

ضع ملف المواصفات في جذر المستودع:

openapi.yaml

وتعامل معه ككود:

كل تغيير يمر عبر PR.
التغييرات الكاسرة تحتاج مراجعة واضحة.
لا تعدّل fixtures بمعزل عن spec.
إذا لم يكن لديك spec، أنشئ مسودة من إطار العمل المستخدم مثل FastAPI أو NestJS، ثم حسّنها يدويًا.

يمكن لـ Apidog أيضًا المساعدة في بناء مواصفات من حركة API عند استيراد ملفات HAR.

الخطوة 2: ثبّت Playwright

npm init playwright@latest

أضف سكريبتات الاختبار:

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:smoke": "playwright test --grep @smoke"
  }
}

مثال playwright.config.ts مختصر:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: 2,
  workers: 4,
  use: {
    baseURL: process.env.APP_BASE_URL ?? 'https://staging.example.com',
    trace: 'on-first-retry',
  },
});

الخطوة 3: ابنِ سيناريوهات Apidog

أنشئ سيناريو لكل رحلة حرجة:

التسجيل.
تسجيل الدخول.
إنشاء طلب.
الدفع.
رد الأموال.
webhook delivery.
idempotency checks.

داخل كل سيناريو:

نفّذ request.
خزّن قيمًا مثل order_id أو payment_id.
استخدمها في الخطوات التالية.
شغّل schema validation.
أضف assertions لمنطق العمل.

مثال تدفق:

POST /auth/token
POST /orders
GET /orders/{id}
POST /payments
GET /payments/{id}

ثم صدّر السيناريو للتشغيل عبر CLI:

apidog-cli run ./apidog/scenarios/checkout.json

استخدام page.route لعزل الواجهة

عندما تريد اختبار UI دون الاعتماد على backend مباشر، استخدم page.route مع نفس fixtures:

// tests/dashboard.spec.ts
import { test, expect } from './fixtures/api';

test('dashboard renders cached order list when offline', async ({
  page,
  sampleOrder,
}) => {
  await page.route('**/api/orders', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ orders: [sampleOrder] }),
    });
  });

  await page.goto('/dashboard');

  await expect(page.getByTestId('order-row')).toHaveCount(1);
});

هذا مفيد لعزل الواجهة، لكنه ليس بديلًا لاختبار API الحقيقي. لذلك شغّل في Apidog سيناريو GET /orders مقابل backend الفعلي أو mock server.

تشغيل Playwright و Apidog في GitHub Actions

أضف workflow يشغّل المجموعتين:

name: tests

on: [push, pull_request]

jobs:
  playwright:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - run: npx playwright install --with-deps

      - run: npx playwright test
        env:
          APP_BASE_URL: ${{ secrets.APP_BASE_URL }}
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          QA_PASSWORD: ${{ secrets.QA_PASSWORD }}

  apidog:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm i -g apidog-cli

      - run: apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          QA_PASSWORD: ${{ secrets.QA_PASSWORD }}

أي فشل في Playwright أو Apidog يمنع الدمج.

تغطي وثائق GitHub Actions إعداد المصفوفات، التخزين المؤقت، وتشغيل jobs بالتوازي.

اكتشاف انحراف العقد مبكرًا

أضف مهمة يومية تقارن المواصفات الحالية بالنسخة المستخدمة في الاختبارات. الفكرة:

openapi-diff old-openapi.yaml openapi.yaml

إذا تغيّر نوع حقل أو اختفى حقل مطلوب، افشل البناء قبل تشغيل الاختبارات.

هذا يلتقط فئة أخطاء مثل:

200 OK
لكن body لا يطابق العقد

وهي المشكلة التي لا تلتقطها اختبارات UI غالبًا.

تقنيات عملية لتحسين الاستقرار

فعّل Playwright trace

في playwright.config.ts:

use: {
  trace: 'on-first-retry',
}

عند الفشل تحصل على:

network timeline.
DOM snapshots.
console logs.
screenshots.

ادمج ذلك مع تقارير Apidog لتعرف هل الانهيار بدأ من الواجهة أم من API.

استخدم mock server من Apidog

عندما تكون بيئة staging غير مستقرة، شغّل mock server من OpenAPI spec، ثم وجّه تطبيقك إليه محليًا.

النمط المقترح:

Playwright يعمل ضد mock server عند الحاجة لعزل UI.
Apidog يعمل ضد backend الحقيقي للتحقق من العقد.
نفس fixtures تُستخدم في الحالتين.

للمزيد حول توليد اختبارات API، راجع إنشاء اختبارات واجهة برمجة التطبيقات بمساعدة الذكاء الاصطناعي.

لا ترفع retries أكثر من اللازم

استخدم:

retries: 2

إذا احتاج الاختبار إلى 5 محاولات، فالمشكلة ليست في CI فقط. لديك test flaky أو backend غير مستقر. في سيناريوهات Apidog، اجعل retry لكل request محدودًا.

افشل عند انحراف المخطط

لا تجعل schema mismatch مجرد warning. يجب أن يفشل CI.

إذا احتجت إلى فترة انتقالية، اجعلها صريحة:

ALLOW_SCHEMA_DRIFT=true

واطلب تعليقًا في PR يشرح السبب.

صنّف الاختبارات

استخدم tags:

test('checkout @smoke', async ({ page }) => {
  // ...
});

استراتيجية تشغيل مقترحة:

@smoke على كل push.
regression على PR إلى main.
سيناريوهات Apidog الكاملة ليلًا.
الاختبارات ذات الحالة stateful تعمل serial.

test.describe.configure({ mode: 'serial' });

أخطاء شائعة يجب تجنبها

الاكتفاء بـ status === 200.
تخزين bearer tokens داخل fixtures.
استخدام fixtures مختلفة بين Playwright و Apidog.
تجاهل تشغيل Apidog CLI في CI.
اعتبار page.route بديلًا لاختبار API الحقيقي.
تعديل OpenAPI بدون تحديث السيناريوهات.
بناء assertions كثيرة داخل اختبار UI بدل نقلها إلى طبقة API.

للاختبارات غير الحتمية، خصوصًا مع وكلاء الذكاء الاصطناعي، راجع كيفية اختبار واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي.

مقارنة الأدوات

المكدس	نقاط القوة	نقاط الضعف	الأفضل لـ
Playwright وحده	أداة واحدة، سريع، مدمج مع اختبارات UI	تحقق محدود من المخطط، سيناريوهات API متسلسلة أصعب	فرق صغيرة وواجهات API بسيطة
Playwright + Postman	نظام Postman ناضج، Newman CLI	احتمال وجود مصدرين للحقيقة وانحراف collections عن OpenAPI	فرق تستخدم Postman بالفعل
Playwright + Apidog	OpenAPI كمصدر واحد، schema validation، mock server، CLI لـ CI	أداتان للتعلم، ويتطلب انضباطًا في المواصفات	فرق تريد اختبارًا موجهًا بالمواصفات
Cypress + cy-api	مألوف لمستخدمي Cypress	اختبار API أقل مرونة، والاعتماد على plugins	مشاريع Cypress الحالية
Pact	عقود قوية بين الخدمات	منحنى تعلم أعلى ولا يركز على UI	منظمات microservices كثيرة المستهلكين

إذا كنت تنتقل من أدوات أقدم، راجع:

حالات استخدام واقعية

checkout في التجارة الإلكترونية

Playwright يتحقق من رحلة المستخدم من السلة إلى صفحة التأكيد. Apidog يتحقق من سلسلة API:

POST /orders
POST /payments
GET /inventory
POST /refunds

إذا تغيّر حقل مثل error_code إلى errorCode، يلتقط Apidog انحراف المخطط بسرعة، بينما قد يعرض Playwright رسالة عامة مثل "فشل الدفع".

لوحة تحكم SaaS للرسوم البيانية

Playwright يتحقق من ظهور الرسم البياني. Apidog يتحقق من أن endpoints التجميع تعيد:

المجاميع الصحيحة.
النسب المئوية.
السلاسل الزمنية المتوقعة.
الحقول المطلوبة حسب OpenAPI.

بهذا لا تمر شاشة جميلة فوق بيانات خاطئة.

webhooks في fintech

Playwright يغطي البوابة المرئية. Apidog يغطي:

webhook delivery.
retry behavior.
idempotency.
signature validation.
رفض webhook مكرر.
نافذة eventual consistency أقل من 30 ثانية.

الخلاصة

Playwright ممتاز لاختبارات المتصفح، لكنه ليس كافيًا لاختبار API بعمق. الإعداد العملي هو:

OpenAPI spec واحد كمصدر حقيقة.
fixtures مشتركة بين Playwright و Apidog.
Playwright لتدفقات UI وnetwork stubbing.
Apidog للتحقق من schema، السيناريوهات المتسلسلة، ومسارات الأخطاء.
CI واحد يشغّل المجموعتين ويفشل عند أي انحراف.

ابدأ برحلة حرجة واحدة مثل التسجيل أو الدفع. اربط fixture في Playwright، أنشئ سيناريو Apidog مطابقًا، ثم شغّلهما معًا في CI. بعد ذلك وسّع التغطية endpoint تلو الآخر.

الأسئلة الشائعة

هل يمكنني التحقق من API داخل Playwright بدون Apidog؟

نعم. يمكنك استخدام أداة request في Playwright مع expect. هذا مناسب لفحوصات بسيطة مثل status code وبعض الحقول. لكن للتحقق من المخطط، السيناريوهات المتسلسلة، المحاكاة، ومسارات الأخطاء على نطاق أوسع، أداة مخصصة مثل Apidog ستكون أكثر عملية. راجع مقارنة أدوات اختبار واجهة برمجة التطبيقات لمهندسي ضمان الجودة.

هل أحتاج إلى OpenAPI spec؟

نعم إذا أردت الفائدة الكاملة. بدون OpenAPI يمكنك تشغيل Playwright و Apidog جنبًا إلى جنب، لكنك ستفقد المصدر المشترك للحقيقة وستضطر لصيانة الأمثلة في أكثر من مكان.

كيف أتعامل مع المصادقة؟

اجلب token جديدًا في بداية الاختبار:

const res = await apiRequest.post('/auth/token', {
  data: { email, password },
});

ثم خزّنه في Playwright fixture وفي متغير بيئة داخل Apidog. لا تحفظ tokens ثابتة داخل المستودع.

هل يمكن أن يحل Apidog محل Playwright؟

لا. Apidog يختبر API workflows، لكنه لا يشغّل متصفحًا ولا يتحقق من عناصر الواجهة. استخدم Playwright للنصوص المرئية، النقرات، التنقل، والتخطيط. استخدم Apidog للعقد والمخططات وسلاسل API.

ماذا أفعل إذا لم تكن بيئة staging مستقرة؟

استخدم mock server من Apidog مبنيًا على OpenAPI. شغّل Playwright ضد mock server لعزل الواجهة، وشغّل سيناريوهات Apidog ضد backend الحقيقي عندما تكون البيئة متاحة.

كيف أحافظ على سرعة CI؟

شغّل @smoke على كل push.
شغّل regression على PRs.
شغّل سيناريوهات Apidog الكاملة ليلًا.
استخدم workers: 4 في Playwright.
شغّل سيناريوهات Apidog بالتوازي إذا كان CLI يدعم ذلك في إعدادك.

هل أحتاج إلى خطة مدفوعة من Apidog لتشغيل CI؟

تحقق من صفحة الأسعار الحالية قبل الاعتماد على نطاق واسع. عادةً يمكن للفرق الصغيرة البدء بالطبقة المجانية، لكن قرار الترخيص يعتمد على حجم الفريق، التعاون، واحتياجات التشغيل.

OpenAI Daybreak ضد Claude Mythos: مقارنة شاملة

Yusuf Khalidd — Tue, 12 May 2026 06:10:40 +0000

أطلق اثنان من أهم مختبرات الذكاء الاصطناعي في العالم منصات للأمن السيبراني خلال خمسة أسابيع فقط. أعلنت Anthropic عن Claude Mythos في 7 أبريل 2026، ثم تبعتها OpenAI بمنصة Daybreak في 11 مايو 2026.

جرّب Apidog اليوم

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

هذا الدليل يقارن بين Claude Mythos و OpenAI Daybreak من زاوية عملية: أيهما يمكنك استخدامه، متى تختاره، وكيف تدمجه في سير عمل فريقك.

الإجابة المختصرة

Claude Mythos هو نموذج بحثي متطور من Anthropic، محجوب عمدًا خلف كونسورتيوم قائم على الدعوات فقط باسم Project Glasswing. وفق الأرقام المنشورة، هو النموذج الأقوى في اكتشاف الثغرات واستنساخها. لكن غالبًا لن تستطيع الوصول إليه.

OpenAI Daybreak هي منصة مبنية حول GPT-5.5، بثلاثة مستويات وصول، ومكون إضافي لأمن Codex، ونظام شركاء أوسع. قدراتها المنشورة أكثر تحفظًا، لكنها أقرب إلى منتج يمكن لفريق أمني استخدامه فعليًا.

الخلاصة العملية:

إذا أردت أعلى قدرة خام لاكتشاف الثغرات: Mythos يتقدم نظريًا.
إذا أردت أداة يمكن نشرها هذا الربع داخل فريقك: Daybreak يتقدم عمليًا.

مقارنة سريعة

الميزة	Claude Mythos	OpenAI Daybreak
تاريخ الإطلاق	7 أبريل 2026	11 مايو 2026
المورد	Anthropic	OpenAI
النوع	نموذج بحثي متطور	منصة: نماذج متعددة + Codex Security
التوفر العام	لا، Project Glasswing فقط	نعم، مع مستويات تحقق
المستويات	نموذج بحثي واحد	GPT-5.5 / وصول موثوق للأمن السيبراني / GPT-5.5-Cyber
منصة الكود	Claude Code	مكون إضافي لأمن Codex
معدل نجاح CTF	73% في CTFs مستوى الخبراء	لم يتم الكشف عنه علنًا
اكتشاف الثغرات غير المعلنة	الآلاف في اختبار ما قبل الإصدار	القدرة مدعاة، دون أرقام عامة
استنساخ الثغرات	83% نجاح في المحاولة الأولى	لم يتم الكشف عنه علنًا
الشركاء	حوالي 40 منظمة منها AWS وApple وMicrosoft وGoogle وCrowdStrike وPalo Alto	أكثر من 20 بائعًا منهم Cisco وCloudflare وSnyk وTenable وFortinet وZscaler
نموذج الوصول	دعوة فقط عبر Project Glasswing	تقديم + تدقيق للمستويات المرتفعة
حالة الاستخدام الأساسية	البحث في ثغرات البنية التحتية الحيوية	سير عمل تطوير آمن ومستمر
التسعير	لم يتم الكشف عنه	تسعير منصة OpenAI للمستويات المتاحة

ما هو Claude Mythos؟

معاينة Claude Mythos هي نموذج Anthropic متقدم يتجاوز عائلة Claude 4 العامة. النموذج متعدد الأغراض، لكنه موجه بقوة نحو التفكير طويل الأمد وأمن البرمجيات.

الأرقام المنشورة حول Mythos قوية:

حقق 73% في تحديات CTF على مستوى الخبراء.
حدد الآلاف من الثغرات غير المعلنة في اختبارات ما قبل الإصدار عبر أنظمة تشغيل ومتصفحات رئيسية.
استنسخ الثغرات وأنتج استغلالات عاملة في المحاولة الأولى بنسبة 83%.

لكن هذه القدرة تأتي مع مخاطرة. لذلك لم تطلق Anthropic النموذج للعامة. بدلًا من ذلك، أنشأت Project Glasswing: كونسورتيوم خاص يستخدم Mythos لتعزيز البرمجيات الحيوية قبل أن تتوفر قدرات مشابهة للمهاجمين.

يشمل Project Glasswing شركات مثل AWS وApple وMicrosoft وGoogle وCrowdStrike وPalo Alto Networks، إضافة إلى حوالي 40 منظمة أخرى عبر الدعوة فقط.

ماذا يعني ذلك عمليًا؟

إذا لم تكن ضمن Project Glasswing:

لا يوجد مسار تسجيل عام.
لا توجد صفحة تسعير.
لا توجد قائمة انتظار معلنة.
لا يمكنك بناء خطة أمنية تعتمد على الوصول إلى Mythos.

يمكنك فقط متابعة التقارير العامة، مثل تقييمات AISI، واستخدام نماذج Claude العامة في المهام الأمنية المصرح بها.

ما هو OpenAI Daybreak؟

Daybreak ليست نموذجًا واحدًا، بل منصة تجمع بين مستويات قدرات مختلفة وأداة وكيلية تعتمد على Codex ونظام شركاء واسع.

المستويات الثلاثة هي:

GPT-5.5: النموذج العام، متاح لمستخدمي OpenAI.
GPT-5.5 مع وصول موثوق للأمن السيبراني: للمدافعين المعتمدين، مع معدلات رفض أقل لأعمال أمنية مشروعة مثل تحليل البرمجيات الخبيثة والهندسة العكسية.
GPT-5.5-Cyber: معاينة محدودة لفرق الهجوم المصرح بها واختبار الاختراق في بيئات مسموح بها.

الطبقة التشغيلية هي Codex Security. الفكرة العملية:

توصيله بمستودع الكود.
بناء نموذج تهديد من قاعدة الكود.
مراقبة مستمرة للثغرات.
إرسال النتائج إلى أدوات الأمان الحالية.
إنشاء تصحيحات والتحقق منها داخل نفس الحلقة.

غطينا المنصة بمزيد من التفصيل في: ما هو OpenAI Daybreak.

باختصار: Daybreak مصممة لفرق الأمن التي تريد دمج الذكاء الاصطناعي داخل سير العمل اليومي، وليس فقط استدعاء نموذج بحثي يدويًا عند الحاجة.

القدرة: أين يتفوق Mythos؟

على مستوى المقاييس المنشورة، Mythos يتقدم.

1. اكتشاف الثغرات

وجد Mythos آلاف الثغرات غير المعلنة في اختبارات ما قبل الإصدار على أنظمة التشغيل والمتصفحات.

تدعي OpenAI قدرة مشابهة في GPT-5.5-Cyber، لكنها لم تنشر أرقامًا قابلة للمقارنة.

2. استنساخ الثغرات

ينتج Mythos استغلالات عاملة في المحاولة الأولى بنسبة 83% من الوقت.

هذا مهم لفرق:

Red Teaming
اختبار الاختراق
التحقق من قابلية الاستغلال
ترتيب أولويات الإصلاح

3. التفكير طويل الأمد

يمكن لـ Mythos تنفيذ مهام متعددة المراحل: اكتشاف، استغلال، وما بعد الاستغلال، مع الحفاظ على السياق.

هذا النوع من العمل قد يستغرق أيامًا من محلل بشري محترف.

4. التقييم المستقل

أكد تقييم معهد سلامة الذكاء الاصطناعي في المملكة المتحدة لقدرات Mythos السيبرانية قفزة كبيرة مقارنة بالجيل السابق. نشر AISI أيضًا تقييمًا لقدرات GPT-5.5 السيبرانية، لكن الأرقام الرئيسية المنشورة تميل لصالح Mythos.

إذا كان سؤالك هو: "أي نموذج أفضل في العثور على الثغرات واستغلالها الآن؟" فالإجابة هي Mythos.

التوفر وسير العمل: أين يتفوق Daybreak؟

القدرة التي لا تستطيع الوصول إليها لا تساعد فريقك.

1. التوزيع

يمكن لأي شخص لديه حساب OpenAI استخدام GPT-5.5 في أعمال أمنية مشروعة اليوم.

أما الوصول الموثوق للأمن السيبراني فيتطلب طلبًا وتحققًا. ومع ذلك، يوجد مسار واضح.

في المقابل، Mythos متاح بالدعوة فقط، ولا يوجد مسار عام للوصول إليه.

2. تكامل سير العمل

Codex Security منتج مصمم للاتصال بالمستودعات والأدوات الأمنية والعمل باستمرار.

سير عمل Daybreak أقرب إلى هذا النمط:

Repository
   ↓
Codex Security
   ↓
Threat model + vulnerability scan
   ↓
Security tools / tickets / pull requests
   ↓
Patch generation + verification

أما Mythos عبر Glasswing فهو أقرب إلى برنامج بحث ثغرات موجّه لشركاء محددين، وليس منتجًا عامًا مدمجًا في أدوات المطورين.

3. النظام البيئي

Daybreak يأتي مع تكاملات عبر طبقات متعددة:

نقاط النهاية: CrowdStrike وSentinelOne
السحابة: Cloudflare وAkamai
الهوية: Okta
أمان الكود: Snyk وSemgrep وSocket
إدارة الثغرات: Qualys وRapid7 وTenable

Project Glasswing لديه شركاء كبار، لكن نطاقه أضيق وأقل توجهًا لسير عمل المطور اليومي.

4. الخدمة الذاتية

يمكن لفريقك التعامل مع Daybreak كمنتج:

إنشاء حساب.
استخدام GPT-5.5.
التقديم للوصول الموثوق إذا كنت تحتاجه.
ربط المستودعات.
دمج النتائج مع أدوات الأمن الحالية.

لا يوجد مسار مشابه لـ Mythos.

لذلك، بالنسبة لمعظم فرق الأمن والهندسة: Daybreak هو الخيار القابل للتنفيذ.

كيف تقرر بينهما؟

استخدم هذا القرار العملي:

هل أنت شريك في Project Glasswing؟
├─ نعم
│  ├─ استخدم Mythos للبحث العميق عن الثغرات في الأنظمة الحيوية
│  └─ استخدم Daybreak لسير العمل الدفاعي اليومي
└─ لا
   ├─ قيّم Daybreak الآن
   ├─ استخدم Claude Code أو GPT-5.5 للمهام الأمنية المصرح بها
   └─ تابع Mythos عبر التقارير العامة فقط

صياغة "Mythos مقابل Daybreak" جذابة إعلاميًا، لكنها غير دقيقة لمعظم الفرق.

في الواقع، الخيار العملي هو:

Daybreak الآن، أو انتظار وصول Mythos غير مضمون.

الفلسفة: رهانان مختلفان على السلامة

الاختلاف الأعمق ليس تقنيًا فقط، بل يتعلق بطريقة إطلاق القدرات الخطيرة.

رهان Anthropic

هذه القدرة قوية وخطيرة جدًا للإطلاق العام. الأفضل استخدامها بشكل خاص مع شركاء موثوقين لتأمين البرمجيات الحيوية قبل أن يحصل المهاجمون على قدرات مشابهة.

في هذا النموذج، Project Glasswing هو المنتج الحقيقي، وليس Mythos وحده.

رهان OpenAI

يمكن توسيع الوصول بأمان عبر:

التحقق من المستخدمين
تقسيم مستويات الوصول
فرض ضوابط أمان الحساب
دمج القدرات داخل سير عمل دفاعي

في هذا النموذج، النظام التشغيلي والحوكمة هما الضمان.

كلا النهجين منطقي. نهج Anthropic يقلل انتشار القدرات الهجومية، لكنه يحد من الفائدة الدفاعية لفئة صغيرة. نهج OpenAI يتيح قدرات أكثر لعدد أكبر من المدافعين، لكنه يعتمد على قوة نظام التحقق.

ماذا عن Claude Code لأعمال الأمن؟

إذا لم تتمكن من الوصول إلى Mythos، يمكنك استخدام Claude Code مع عائلة Claude 4 العامة في مهام أمنية مشروعة.

أمثلة عملية:

مراجعة كود بحثًا عن أنماط خطرة.
شرح مسارات تنفيذ معقدة.
توليد فرضيات حول نقاط الضعف.
كتابة اختبارات تحقق للمدخلات.
اقتراح تصحيحات للكود.

مثال طلب آمن ومفيد:

راجع هذا المسار البرمجي وحدد أين قد يحدث تجاوز صلاحيات.
لا تكتب كود استغلال.
اقترح اختبارات وحدة وتعديلات تحقق من الصلاحيات.

غطينا واجهة Claude الأوسع هنا: احصل على وصول مجاني غير محدود إلى واجهة برمجة تطبيقات Claude.

بالنسبة لفرق الأمن المستثمرة في Anthropic، هذا هو المسار الواقعي إلى أن يتغير توفر Glasswing أو يتم إطلاق نموذج لاحق للعامة.

المسار المكافئ في OpenAI هو استخدام واجهة برمجة تطبيقات GPT-5.5 للمهام الأمنية قبل التقديم للوصول الموثوق للأمن السيبراني.

خطة تنفيذ لفريق أمني صغير

إذا كنت تريد تجربة هذا النوع من الأدوات دون انتظار Mythos، ابدأ بخطة بسيطة:

الأسبوع 1: تحديد النطاق

اختر مستودعًا واحدًا فقط:

خدمة API داخلية
خدمة مصادقة
خدمة دفع
خدمة تتعامل مع بيانات حساسة

لا تبدأ بكل المستودعات.

الأسبوع 2: إنشاء خط أساس

وثّق:

نقاط النهاية الحساسة
نماذج الصلاحيات
التبعيات الحرجة
آخر ثغرات معروفة
الاختبارات الأمنية الموجودة

مثال قائمة فحص:

- [ ] هل كل endpoint يتطلب مصادقة؟
- [ ] هل يوجد تحقق تفصيلي من الصلاحيات؟
- [ ] هل يتم التحقق من schema للطلبات؟
- [ ] هل توجد حدود rate limiting؟
- [ ] هل توجد اختبارات للمدخلات غير الصالحة؟
- [ ] هل التبعيات محدثة؟

الأسبوع 3: دمج Daybreak أو أدوات مكافئة

ابدأ بالمهام الدفاعية:

مراجعة الكود.
توليد اختبارات.
اقتراح تصحيحات.
تلخيص المخاطر.
ترتيب الأولويات.

لا تستخدم النموذج لتوليد استغلالات ضد أنظمة لا تملكها أو لا تملك تصريحًا لاختبارها.

الأسبوع 4: تحويل النتائج إلى سير عمل

لا تجعل النتائج تبقى في محادثة AI فقط. اربطها بعملية التطوير:

Finding → Issue → Owner → Pull Request → Security Review → Regression Test

الهدف ليس "استخدام نموذج ذكي"، بل تقليل زمن اكتشاف الثغرة وإصلاحها.

ماذا يعني هذا لمطوري واجهات برمجة التطبيقات API؟

تستهدف كثير من الهجمات الإنتاجية واجهات برمجة التطبيقات:

تجاوز المصادقة
الترخيص المعطل
حقن المدخلات
انحراف العقد بين التوثيق والتنفيذ
ثغرات التبعيات في خدمات backend
اختلاف السلوك بين البيئات

لا Mythos ولا Daybreak هما أداة متخصصة فقط في أمان API. كلاهما يمكنه تحليل كود API، لكنهما يتعاملان معه كجزء من قاعدة كود أوسع.

لذلك، لأمان API عملي، استخدم طبقتين:

أداة تصميم واختبار API مثل Apidog
نموذج أمني مثل Daybreak أو، إن توفر، Mythos

Apidog يساعدك في اكتشاف مشاكل مثل:

انحراف العقد contract drift
مخططات request/response المعطلة
تغيرات السلوك بين الإصدارات
أخطاء الاختبار في خوادم MCP

يمكنك بناء هذا المسار:

API spec
   ↓
Contract-first development
   ↓
Automated API tests
   ↓
AI security review
   ↓
Patch + regression test

اقرأ أيضًا:

الفكرة العملية: استخدم Apidog لضبط العقد والسلوك، واستخدم Daybreak أو Mythos لاكتشاف العيوب المنطقية القابلة للاستغلال في التنفيذ.

الأسئلة الشائعة

هل Claude Mythos متاح للجمهور؟

لا. Mythos محدود لشركاء Project Glasswing. لم تعلن Anthropic عن جدول زمني لإطلاق عام. اعتبارًا من مايو 2026، لا توجد عملية تقديم للأفراد أو المؤسسات الأصغر.

هل يمكنني الحصول على وصول موثوق للأمن السيبراني في OpenAI؟

نعم، مع التحقق. يمكنك التقديم عبر منصة OpenAI. يعتمد القبول على حالات استخدام دفاعية مشروعة. يتطلب الوصول الفردي إلى GPT-5.5-Cyber تمكين أمان الحساب المتقدم بحلول 1 يونيو 2026.

هل Mythos أكثر قدرة من GPT-5.5-Cyber؟

وفق المقاييس المنشورة، نعم. حقق Mythos نسبة 73% في تحديات CTF للمحترفين، وينتج استغلالات عاملة في المحاولة الأولى بنسبة 83% من الوقت. لم تنشر OpenAI أرقامًا مكافئة لـ GPT-5.5-Cyber.

قد تتغير الفجوة مع نضوج Daybreak وإطلاق OpenAI نماذج سيبرانية أكثر قدرة.

هل Mythos وDaybreak منتجان متنافسان؟

من ناحية التموضع، نعم. عمليًا، ليس تمامًا.

Mythos نموذج بحثي خلف كونسورتيوم خاص. Daybreak منصة يمكن لفريقك التقديم لاستخدامها ودمجها في سير العمل.

لذلك، معظم الفرق لا تختار بين المنتجين مباشرة، بل تختار بين:

استخدام Daybreak الآن
أو انتظار وصول Mythos العام، إن حدث

هل يمكن استخدام أي من النموذجين للأمن الهجومي ضد أطراف ثالثة؟

لا. كلاهما يتضمن ضمانات ضد استغلال أنظمة لا تملكها أو لا تملك تصريحًا لاختبارها.

يدعم GPT-5.5-Cyber فرق Red Teaming واختبار الاختراق داخل بيئات مصرح بها. ويُستخدم Mythos عبر Glasswing لاكتشاف الثغرات دفاعيًا في أنظمة الشركاء.

الاستخدام الهجومي ضد أطراف ثالثة محظور بغض النظر عن مستوى الوصول.

كيف يقارن هذا مع Microsoft Security Copilot؟

يركز Microsoft Security Copilot على عمليات مركز العمليات الأمنية SOC، مثل:

فرز التنبيهات
الاستجابة للحوادث
استخبارات التهديدات
التحقيقات التشغيلية

أما Daybreak وMythos فيركزان أكثر على اكتشاف الثغرات على مستوى الكود ومعالجتها.

هما يغطيان أجزاء مختلفة من سير عمل الأمان. سياق ذو صلة: ما هو GPT Realtime 2 وكيفية استخدام واجهة برمجة التطبيقات.

الخلاصة

هذه أول مرة يطلق فيها مختبران رائدان في الذكاء الاصطناعي منصات أمن سيبراني متنافسة في الربع نفسه. لكن الاختلافات العملية كبيرة:

Mythos أقوى وفق المقاييس المنشورة، لكنه غير متاح لمعظم الفرق.
Daybreak أقل وضوحًا من ناحية الأرقام العامة، لكنه قابل للتقييم والنشر.
Claude Code وGPT-5.5 يوفران مسارات عملية للمهام الأمنية اليومية المصرح بها.
أمان API يحتاج أدوات متخصصة بجانب نماذج الذكاء الاصطناعي.

القرار العملي لفريقك:

قيّم Daybreak الآن إذا كان متاحًا لك.
استخدم نماذج عامة في مراجعة الكود والاختبارات الأمنية المصرح بها.
تابع Mythos عبر التقارير العامة، ولا تبنِ خطتك على وصول غير مضمون.
اربط أي نموذج أمني بسير عمل واضح: اكتشاف، تذكرة، تصحيح، اختبار رجعي.

خطط للأدوات التي يمكنك نشرها، لا للنماذج التي قد لا تحصل عليها.

كيفية تتبع تكلفة استخدام API أوبن إيه آي (OpenAI) لكل ميزة: دليل لتحديد مصادر التكلفة

Yusuf Khalidd — Tue, 12 May 2026 02:42:27 +0000

فاتورة OpenAI تقول إنك أنفقت 4,237 دولارًا الشهر الماضي. لكنها لا تقول إن 3,100 دولار جاءت من نقطة نهاية تلخيص خرجت عن السيطرة، و700 دولار من عميل يدفع 50 دولارًا شهريًا، و437 دولارًا من ميزة لا يستخدمها أحد. إذا كنت تشحن ميزات تعتمد على نماذج اللغة الكبيرة، فأنت تحتاج إلى إسناد التكلفة لكل طلب، لا إلى رقم إجمالي في لوحة الفوترة.

جرّب Apidog اليوم

يوضح هذا الدليل طريقة عملية لإسناد تكلفة OpenAI API: وسم كل طلب ببيانات وصفية، تسجيل التوكنات والتكلفة، التجميع حسب الميزة والمسار والعميل، تعيين حدود ميزانية، واختبار الغلاف قبل الإنتاج.

💡 يمنحك Apidog رؤية على مستوى الطلب واختبار السيناريوهات للتحقق من أن غلاف تتبع التكلفة يعمل قبل نشره. استخدمه لإعادة تشغيل الطلبات الموسومة، تأكيد شكل السجل، والتحقق من أن كل استدعاء يحمل البيانات الوصفية التي يتوقعها مستودع البيانات.

باختصار

نفّذ الآتي:

وسّم كل استدعاء OpenAI بـ feature وroute وcustomer_id وenvironment.
سجّل حدث JSON لكل طلب يحتوي على التوكنات، النموذج، زمن الاستجابة، والتكلفة المحسوبة.
خزّن الأحداث في BigQuery أو ClickHouse أو Snowflake أو Postgres.
اجمع الإنفاق حسب الميزة، العميل، والمسار.
عيّن حدودًا لكل مفتاح مشروع في OpenAI.
أضف تنبيهات مبنية على مستودع البيانات.
اختبر الغلاف باستخدام Apidog قبل الاعتماد على الأرقام.

لماذا لا تكفي لوحة تحكم فواتير OpenAI

لوحة تحكم OpenAI تعرض إجمالي الإنفاق، تفصيلًا حسب النموذج، وحدود الاستخدام. هذا مفيد للفوترة، لكنه غير كافٍ لاتخاذ قرارات هندسية أو منتجية.

المشكلات العملية:

لا يوجد سياق للإنفاق: ترى أنك أنفقت 312 دولارًا أمس، لكن لا تعرف هل السبب عميل واحد، ميزة جديدة، أم وظيفة خلفية.
لا يوجد تفصيل لكل ميزة: OpenAI تميّز الطلبات حسب مفتاح API والنموذج، لا حسب feature أو route أو customer_id.
تأخر في بيانات الاستخدام: بيانات لوحة التحكم قد تتأخر عشرات الدقائق أو ساعات.
تنبيهات محدودة: لا يوجد تنبيه أصلي مثل: "أرسل تنبيهًا إذا تجاوزت ميزة الدردشة 50 دولارًا في الساعة".
لا يوجد إسناد للعملاء: لا يمكنك حساب تكلفة العميل X أو هامش الربح لكل عميل من لوحة التحكم وحدها.
مفاتيح المشاريع تساعد جزئيًا فقط: تعطيك بُعدًا واحدًا للإسناد، لكنها لا تحل إسناد الميزة أو العميل أو المسار.

تستطيع استخدام واجهة استخدام OpenAI للمصالحة والتجميع، لكنها لا تعطيك حدثًا تفصيليًا لكل طلب. لذلك تحتاج إلى طبقة إسناد داخل التطبيق.

للسياق حول التسعير، راجع تفاصيل تسعير GPT-5.5. ولمشكلة مشابهة في أدوات المطورين، راجع فاتورة استخدام GitHub Copilot لفرق واجهات برمجة التطبيقات. ولأساسيات OpenAI API، راجع المرجع الرسمي لـ OpenAI API.

نموذج بيانات إسناد التكلفة

اجعل كل طلب OpenAI ينتج حدثًا واحدًا منظّمًا. هذا الحدث هو مصدر الحقيقة للوحات التحكم والتنبيهات والتقارير.

العمود	النوع	مثال	لماذا هو مهم
`request_id`	uuid	`7a91...`	الثبات، إزالة التكرار، إعادة المحاولات
`timestamp`	timestamptz	`2026-05-06T14:23:01Z`	السلاسل الزمنية والتنبيهات
`feature`	text	`support-chat`	الميزة التي أطلقت الاستدعاء
`route`	text	`/api/v1/chat/answer`	مسار HTTP أو وظيفة الخلفية
`customer_id`	text	`cust_4291`	الإنفاق لكل عميل
`environment`	text	`prod`	فصل الإنتاج عن التطوير
`model`	text	`gpt-5.5`	التسعير يختلف حسب النموذج
`prompt_tokens`	int	`15234`	توكنات الإدخال
`completion_tokens`	int	`812`	توكنات الإخراج
`reasoning_tokens`	int	`4500`	توكنات الاستدلال، وتُحاسب كمخرجات
`cached_tokens`	int	`12000`	توكنات التخزين المؤقت
`latency_ms`	int	`2341`	ربط التكلفة بتجربة المستخدم
`cost_usd`	numeric	`0.045672`	التكلفة المحسوبة وقت الطلب
`prompt_cache_key`	text	`system-v3`	تتبع فعالية التخزين المؤقت
`error_code`	text	`429` أو `null`	تحليل الأخطاء وإعادة المحاولات

احسب التكلفة وقت الكتابة، لا وقت الاستعلام. بهذه الطريقة تبقى البيانات التاريخية مرتبطة بالسعر الذي كان معمولًا به عند تنفيذ الطلب.

PRICING = {  # USD per 1M tokens, as of May 2026
    "gpt-5.5":      {"input": 5.00,  "cached": 2.50,  "output": 30.00},
    "gpt-5.5-pro":  {"input": 30.00, "cached": 15.00, "output": 180.00},
    "gpt-5.4":      {"input": 2.50,  "cached": 1.25,  "output": 15.00},
    "gpt-5.4-mini": {"input": 0.25,  "cached": 0.125, "output": 2.00},
}

def compute_cost_usd(model, prompt_tokens, cached_tokens, completion_tokens, reasoning_tokens):
    rates = PRICING[model]

    uncached = max(0, prompt_tokens - cached_tokens)

    input_cost = (uncached * rates["input"]) / 1_000_000
    cache_cost = (cached_tokens * rates["cached"]) / 1_000_000
    output_cost = ((completion_tokens + reasoning_tokens) * rates["output"]) / 1_000_000

    return round(input_cost + cache_cost + output_cost, 6)

ملاحظة مهمة: توكنات الاستدلال reasoning_tokens تُحاسب كسعر مخرجات. تعيدها OpenAI في usage.completion_tokens_details.reasoning_tokens. إذا تجاهلت ذلك، ستقلل التكلفة الفعلية لطلبات التفكير.

تنفيذ غلاف OpenAI في Python

اجعل كل استدعاء للنموذج يمر عبر دالة واحدة. هذه الدالة تستقبل البيانات الوصفية، تنفذ الطلب، تستخرج usage، تحسب التكلفة، وتكتب سجل JSON.

import time
import uuid
import json
import logging
from openai import OpenAI

client = OpenAI()
logger = logging.getLogger("llm.cost")

def call_with_attribution(
    *,
    feature,
    route,
    customer_id,
    environment,
    model,
    messages,
    request_id=None,
    **openai_kwargs
):
    if not feature or not route or not customer_id or not environment:
        raise ValueError("feature, route, customer_id, and environment are required")

    request_id = request_id or str(uuid.uuid4())
    started = time.time()
    error_code = None
    response = None

    try:
        response = client.chat.completions.create(
            model=model,
            messages=messages,
            **openai_kwargs
        )
        return response

    except Exception as e:
        error_code = getattr(e, "code", "unknown_error")
        raise

    finally:
        latency_ms = int((time.time() - started) * 1000)

        u = response.usage if response else None

        prompt_tokens = getattr(u, "prompt_tokens", 0) if u else 0
        completion_tokens = getattr(u, "completion_tokens", 0) if u else 0

        cached_tokens = (
            getattr(getattr(u, "prompt_tokens_details", None), "cached_tokens", 0)
            if u else 0
        ) or 0

        reasoning_tokens = (
            getattr(getattr(u, "completion_tokens_details", None), "reasoning_tokens", 0)
            if u else 0
        ) or 0

        cost_usd = compute_cost_usd(
            model,
            prompt_tokens,
            cached_tokens,
            completion_tokens,
            reasoning_tokens
        )

        logger.info(json.dumps({
            "event": "openai.request",
            "request_id": request_id,
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
            "feature": feature,
            "route": route,
            "customer_id": customer_id,
            "environment": environment,
            "model": model,
            "prompt_tokens": prompt_tokens,
            "completion_tokens": completion_tokens,
            "reasoning_tokens": reasoning_tokens,
            "cached_tokens": cached_tokens,
            "latency_ms": latency_ms,
            "cost_usd": cost_usd,
            "error_code": error_code,
        }))

استخدم الغلاف من موقع الاستدعاء:

response = call_with_attribution(
    feature="support-chat",
    route="/api/v1/chat/answer",
    customer_id=current_user.account_id,
    environment="prod",
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "أجب كمساعد دعم فني."},
        {"role": "user", "content": user_question},
    ],
)

لا تجعل feature أو customer_id قيمًا اختيارية. إذا غابت، ارفع خطأ. الوسم الناقص يعني إسنادًا خاطئًا.

تنفيذ الفكرة في Node.js

الفكرة نفسها تنطبق على Node.js: غلّف SDK، استخرج response.usage، احسب التكلفة، واكتب سجل JSON.

import OpenAI from "openai";

const client = new OpenAI();

const PRICING = {
  "gpt-5.5": { input: 5.00, cached: 2.50, output: 30.00 },
  "gpt-5.5-pro": { input: 30.00, cached: 15.00, output: 180.00 },
  "gpt-5.4": { input: 2.50, cached: 1.25, output: 15.00 },
  "gpt-5.4-mini": { input: 0.25, cached: 0.125, output: 2.00 },
};

function computeCostUsd(model, promptTokens, cachedTokens, completionTokens, reasoningTokens) {
  const rates = PRICING[model];
  const uncached = Math.max(0, promptTokens - cachedTokens);

  const inputCost = (uncached * rates.input) / 1_000_000;
  const cacheCost = (cachedTokens * rates.cached) / 1_000_000;
  const outputCost = ((completionTokens + reasoningTokens) * rates.output) / 1_000_000;

  return Number((inputCost + cacheCost + outputCost).toFixed(6));
}

export async function callWithAttribution({
  feature,
  route,
  customerId,
  environment,
  model,
  messages,
  requestId = crypto.randomUUID(),
  ...openaiArgs
}) {
  if (!feature || !route || !customerId || !environment) {
    throw new Error("feature, route, customerId, and environment are required");
  }

  const started = Date.now();
  let response;
  let errorCode = null;

  try {
    response = await client.chat.completions.create({
      model,
      messages,
      ...openaiArgs,
    });

    return response;
  } catch (err) {
    errorCode = err.code || "unknown_error";
    throw err;
  } finally {
    const usage = response?.usage;

    const promptTokens = usage?.prompt_tokens ?? 0;
    const completionTokens = usage?.completion_tokens ?? 0;
    const cachedTokens = usage?.prompt_tokens_details?.cached_tokens ?? 0;
    const reasoningTokens = usage?.completion_tokens_details?.reasoning_tokens ?? 0;

    const costUsd = computeCostUsd(
      model,
      promptTokens,
      cachedTokens,
      completionTokens,
      reasoningTokens
    );

    console.log(JSON.stringify({
      event: "openai.request",
      request_id: requestId,
      timestamp: new Date().toISOString(),
      feature,
      route,
      customer_id: customerId,
      environment,
      model,
      prompt_tokens: promptTokens,
      completion_tokens: completionTokens,
      reasoning_tokens: reasoningTokens,
      cached_tokens: cachedTokens,
      latency_ms: Date.now() - started,
      cost_usd: costUsd,
      error_code: errorCode,
    }));
  }
}

إذا كنت تستخدم Kafka أو Pub/Sub أو NATS، انشر الحدث هناك بدلًا من stdout. المهم أن يصل الحدث نفسه إلى مستودع البيانات ونظام التنبيه.

تخزين الأحداث والاستعلام عنها

اشحن السجلات إلى مستودع البيانات عبر المسار الموجود لديك: Vector، Fluent Bit، Logstash، OTLP collector، أو أي ناقل سجلات آخر.

بعدها يصبح التحليل SQL عاديًا.

الإنفاق حسب الميزة

SELECT
  feature,
  DATE_TRUNC(timestamp, DAY) AS day,
  COUNT(*) AS requests,
  SUM(cost_usd) AS spend_usd,
  SUM(prompt_tokens + completion_tokens + reasoning_tokens) AS tokens,
  AVG(latency_ms) AS avg_latency_ms,
  SUM(cached_tokens) / NULLIF(SUM(prompt_tokens), 0) AS cache_hit_rate
FROM openai_events
WHERE environment = 'prod'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY feature, day
ORDER BY day DESC, spend_usd DESC;

الإنفاق حسب العميل

SELECT
  customer_id,
  SUM(cost_usd) AS spend_usd,
  COUNT(*) AS requests,
  AVG(cost_usd) AS avg_cost_per_request
FROM openai_events
WHERE environment = 'prod'
  AND timestamp >= TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), MONTH)
GROUP BY customer_id
ORDER BY spend_usd DESC
LIMIT 50;

أكثر المسارات تكلفة

SELECT
  route,
  feature,
  SUM(cost_usd) AS spend_usd,
  COUNT(*) AS requests,
  AVG(prompt_tokens) AS avg_prompt_tokens,
  AVG(completion_tokens + reasoning_tokens) AS avg_output_tokens
FROM openai_events
WHERE environment = 'prod'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
GROUP BY route, feature
ORDER BY spend_usd DESC
LIMIT 20;

اربط هذه الاستعلامات بـ Grafana أو Metabase أو Looker أو Superset. أنشئ ثلاث لوحات أساسية:

الإنفاق لكل ميزة بمرور الوقت.
الإنفاق لكل عميل بمرور الوقت.
أعلى 20 مسارًا حسب إنفاق آخر 24 ساعة.

اختبار الغلاف باستخدام Apidog

لا تنتظر الإنتاج لاكتشاف أن customer_id فارغ أو أن cost_usd لا يُسجل عند بعض المسارات. اختبر الغلاف كما تختبر أي عقد API.

استخدم Apidog بهذا التسلسل:

أنشئ سيناريو يرسل طلبًا إلى نقطة نهاية الذكاء الاصطناعي في خدمتك.
مرّر customer_id وfeature معروفين.
نفّذ الطلب.
التقط سجل JSON من stdout أو OTLP أو نقطة نهاية السجلات الداخلية.
أضف تأكيدات للتأكد من وجود الحقول التالية:
- feature
- route
- customer_id
- environment
- model
- prompt_tokens > 0
- cost_usd > 0
شغّل السيناريو عبر بيئات التطوير والإنتاج باستخدام متغيرات بيئة Apidog.
أعد تشغيل الطلبات الموسومة وتأكد من أن إعادة المحاولة لا تضاعف التكلفة إذا كانت تستخدم request_id نفسه.

مثال على تأكيد منطقي تريد تطبيقه في الاختبار:

pm.expect(log.event).to.eql("openai.request");
pm.expect(log.feature).to.eql("support-chat");
pm.expect(log.customer_id).to.eql("cust_test_001");
pm.expect(log.cost_usd).to.be.above(0);
pm.expect(log.prompt_tokens).to.be.above(0);

للاطلاع على مقاربات أوسع لاختبار واجهات برمجة التطبيقات، راجع أدوات اختبار واجهات برمجة التطبيقات لمهندسي ضمان الجودة. ولنهج "العقد أولًا"، راجع تطوير واجهة برمجة التطبيقات العقد أولًا.

حدود الميزانية والتنبيهات

استخدم طبقتين من الحماية.

1. حدود OpenAI الأصلية

أنشئ مفاتيح مشروع منفصلة حسب البيئة أو الميزة، مثل:

prod-support-chat
prod-summarization
prod-agent-workflows
staging-all

ثم عيّن حدًا صارمًا لكل مفتاح في لوحة OpenAI. هذا يمنع ميزة واحدة من استنزاف ميزانية المؤسسة كلها.

2. تنبيهات من مستودع البيانات

شغّل استعلامًا كل 10 دقائق. إذا تجاوزت ميزة ما 3 أضعاف متوسط إنفاقها الساعي خلال آخر 7 أيام، أرسل تنبيهًا إلى Slack أو PagerDuty أو Opsgenie.

مثال مبسط:

WITH hourly AS (
  SELECT
    feature,
    TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
    SUM(cost_usd) AS spend_usd
  FROM openai_events
  WHERE environment = 'prod'
    AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  GROUP BY feature, hour
),

baseline AS (
  SELECT
    feature,
    AVG(spend_usd) AS avg_hourly_spend
  FROM hourly
  WHERE hour < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), HOUR)
  GROUP BY feature
),

current_hour AS (
  SELECT
    feature,
    SUM(cost_usd) AS current_spend
  FROM openai_events
  WHERE environment = 'prod'
    AND timestamp >= TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), HOUR)
  GROUP BY feature
)

SELECT
  c.feature,
  c.current_spend,
  b.avg_hourly_spend
FROM current_hour c
JOIN baseline b USING (feature)
WHERE c.current_spend > b.avg_hourly_spend * 3;

الحدود الأصلية تحميك من الكوارث. التنبيهات المبنية على البيانات تلتقط الانحراف البطيء قبل أن يتحول إلى فاتورة كبيرة.

تحسينات متقدمة لتقليل التكلفة

التخزين المؤقت للمطالبات

إذا كان جزء كبير من المطالبة ثابتًا، اجعله في البداية وضع المتغيرات في النهاية. هذا يزيد فرصة الاستفادة من prompt caching.

تتبع هذا المؤشر لكل ميزة:

SELECT
  feature,
  SUM(cached_tokens) / NULLIF(SUM(prompt_tokens), 0) AS cache_hit_rate
FROM openai_events
WHERE environment = 'prod'
GROUP BY feature
ORDER BY cache_hit_rate ASC;

راجع وثائق التخزين المؤقت للمطالبات من OpenAI لمعرفة قواعد الأهلية.

استخدام Batch API للأعمال غير المتزامنة

أي مهمة لا تحتاج استجابة فورية يمكن تشغيلها عبر Batch API:

تلخيص ليلي.
تقييمات.
إعادة معالجة مستندات.
تعبئة embeddings.

استمر في الوسم، وأضف batch_job_id إلى الحدث حتى تستطيع إسناد التكلفة إلى عبء العمل الأصلي.

ضبط جهد الاستدلال

إذا كنت تستخدم وضع التفكير، راجع reasoning.effort. المستويات الأعلى قد ترفع توكنات الإخراج. اختبر الجودة مقابل التكلفة:

شغّل نفس السيناريو على low.
شغّله على medium.
قارن الجودة والتكلفة.
استخدم الخيار الأقل تكلفة إذا كانت الجودة مقبولة.

للتفاصيل العملية، راجع كيفية استخدام GPT-5.5 API.

ضبط حجم السياق

المطالبات الطويلة مكلفة. بدلًا من إدخال قاعدة المعرفة كاملة في السياق، استخدم RAG بميزانية استرجاع واضحة.

راقب تضخم المطالبة:

SELECT
  feature,
  DATE_TRUNC(timestamp, WEEK) AS week,
  AVG(prompt_tokens) AS avg_prompt_tokens
FROM openai_events
WHERE environment = 'prod'
GROUP BY feature, week
ORDER BY week DESC;

إذا ارتفع avg_prompt_tokens أسبوعًا بعد أسبوع بدون تغيير منتجي واضح، فالمطالبة تتضخم.

مراقبة الطلبات القريبة من الحدود الكبيرة

إذا كانت هناك مضاعفات سعرية عند تجاوز حد معين من التوكنات، أضف تحذيرًا داخل الغلاف:

if prompt_tokens > 250000:
    logger.warning(json.dumps({
        "event": "openai.large_prompt_warning",
        "request_id": request_id,
        "feature": feature,
        "route": route,
        "customer_id": customer_id,
        "prompt_tokens": prompt_tokens,
    }))

راجع منشور تسعير GPT-5.5 لتفاصيل التسعير.

حدود إنفاق لكل عميل

إذا كان منتجك B2B SaaS، أضف حدًا شهريًا لكل customer_id.

مثال تحقق قبل استدعاء OpenAI:

def assert_customer_ai_budget(customer_id, monthly_limit_usd):
    current_spend = get_month_to_date_ai_spend(customer_id)

    if current_spend >= monthly_limit_usd:
        raise AiQuotaExceeded(
            "تم تجاوز حصة الذكاء الاصطناعي الشهرية"
        )

ثم استخدمه قبل الغلاف:

assert_customer_ai_budget(
    customer_id=current_user.account_id,
    monthly_limit_usd=current_user.plan.ai_budget_usd
)

response = call_with_attribution(
    feature="support-chat",
    route="/api/v1/chat/answer",
    customer_id=current_user.account_id,
    environment="prod",
    model="gpt-5.5",
    messages=messages,
)

عند تجاوز الحد، أعد 429 أو رسالة واضحة داخل المنتج. هذا يحوّل ميزات الذكاء الاصطناعي من خطر على الهامش إلى منتج يمكن تسعيره.

أخطاء شائعة يجب تجنبها

حساب reasoning_tokens كسعر إدخال. الصحيح أنها تُحاسب كمخرجات.
الاعتماد على لوحة OpenAI للتنبيهات الفورية. استخدم مستودع البيانات.
وضع الوسوم داخل SDK بدل موقع الاستدعاء. الوسم يجب أن يأتي من الميزة.
نسيان وظائف الخلفية مثل Cron وworkers وwebhooks.
أخذ عينات من الطلبات. لا تفعل ذلك؛ سجّل كل طلب.
ترك customer_id فارغًا. استخدم internal أو system إذا لم يوجد عميل.
حساب التكلفة وقت الاستعلام فقط. خزّن cost_usd مع الحدث.
عدم اختبار شكل السجل قبل الإنتاج.

البدائل والأدوات

النهج	ما يبرع فيه	تكلفته	متى تستخدمه
OpenAI usage API	أصلي، لا يتطلب إعدادًا	مجاني	مشروع واحد أو احتياجات بسيطة
Helicone	وكيل مباشر، لوحات تحكم، تخزين مؤقت، تكلفة لكل مستخدم	طبقة مجانية؛ مدفوع يبدأ من 20 دولارًا شهريًا	تريد لوحة مستضافة بسرعة وتقبل وكيلًا في المسار
Langfuse	مفتوح المصدر، تتبع وتكلفة	استضافة ذاتية مجانية؛ سحابة تبدأ من 29 دولارًا شهريًا	تريد تتبعًا وتكلفة في أداة واحدة
LangSmith	تكامل مع LangChain، تقييم وتكلفة	يبدأ من 39 دولارًا لكل مستخدم شهريًا	تستخدم LangChain بالفعل
مستودع بيانات مخصص	تحكم كامل، لا يوجد وكيل، أبعاد مخصصة	وقت هندسي	فرق كبيرة أو متطلبات بيانات صارمة

الوكيل مثل Helicone يضيف قفزة في المسار الحرج. Langfuse يعطيك تحكمًا أكبر لكنك تدير جزءًا من المكدس. المسار المخصص يناسب الفرق التي لديها مستودع بيانات ومراقبة جاهزة. OpenAI usage API جيد للمصالحة، لكنه لا يكفي لإسناد تكلفة المنتج.

للمزيد حول مراقبة تكاليف LLM، راجع دليل Helicone حول تتبع تكاليف LLM ووثائق Langfuse حول تتبع التكلفة.

إذا كنت تدير هذا على مستوى منصة API، راجع منصات واجهات برمجة التطبيقات لهندسة الخدمات المصغرة.

حالات استخدام واقعية

B2B SaaS مع إنفاق LLM لكل عميل

شركة تبيع منتجًا لذكاء المبيعات. كل عميل يشغّل استدعاءات GPT-5.5 عند طلب موجز. بدون إسناد، تعرف الشركة أنها تنفق 80 ألف دولار شهريًا على OpenAI. مع الإسناد لكل عميل، تكتشف أن 12٪ من العملاء يسببون 71٪ من الإنفاق. النتيجة: تسعير متدرج، حصص مرنة، ورسوم تجاوز.

أدوات مطورين داخلية

منظمة هندسية تمنح المطورين مساعد دردشة داخليًا. باستخدام customer_id = dev_email، يرى فريق المنصة أن ثلاثة مطورين يمثلون 50٪ من الإنفاق الداخلي. اثنان منهم يشغلان حلقات وكلاء آلية لم يتم إيقافها. إيقافها يوفر 1,800 دولار شهريًا.

توقع تكلفة ميزة جديدة

فريق منتج يريد شحن ميزة تلخيص. باستخدام بيانات تاريخية لكل ميزة، يحسب:

متوسط توكنات الإدخال لكل طلب.
متوسط توكنات الإخراج.
عدد الطلبات لكل مستخدم نشط.
عدد المستخدمين المتوقع.

الناتج: 0.04 دولار لكل مستخدم نشط يوميًا، أو 1.20 دولار شهريًا. يمكن عندها تسعير الميزة بوضوح بدل التخمين.

الخلاصة

لوحة فواتير OpenAI تجيب على سؤال: "كم دفعنا؟".

إسناد التكلفة يجيب على سؤال: "من تسبب في التكلفة، ولماذا؟".

نفّذ الحد الأدنى التالي:

وسّم كل طلب بـ feature وroute وcustomer_id وenvironment.
احسب cost_usd وقت الطلب.
سجّل حدث JSON واحدًا لكل استدعاء.
خزّن الأحداث في مستودع البيانات.
ابنِ لوحات للإنفاق حسب الميزة والعميل والمسار.
عيّن حدودًا لكل مفتاح مشروع.
اختبر الغلاف باستخدام Apidog قبل الإنتاج.

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

لقراءة ذات صلة بإدارة التكاليف، راجع تفاصيل تسعير GPT-5.5 وفاتورة استخدام GitHub Copilot لفرق واجهات برمجة التطبيقات.

الأسئلة الشائعة

هل تحسب توكنات الاستدلال كمدخلات أم مخرجات؟

كمخرجات. تعيد OpenAI هذه التوكنات تحت:

usage.completion_tokens_details.reasoning_tokens

أضفها إلى completion_tokens عند حساب التكلفة. راجع تفاصيل تسعير GPT-5.5.

ما مدى دقة `response.usage` مقارنة بلوحة OpenAI؟

أعداد التوكنات في response.usage هي المصدر المناسب للحساب على مستوى الطلب. قد يحدث انحراف في التكلفة إذا استخدمت جدول أسعار قديمًا، لذلك ثبّت الأسعار في الكود وحدّثها عند تغيير التسعير.

هل تكفي مفاتيح مشروع OpenAI للإسناد؟

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

ماذا عن إعادة المحاولات؟

إذا فشل الطلب قبل تشغيل النموذج، فلن تحصل عادةً على usage ولن تسجل تكلفة. إذا نجح الطلب ثم أعدته طبقة التطبيق، قد تسجل التكلفة مرتين. مرّر request_id نفسه في إعادة المحاولة واجعل طبقة التخزين تزيل التكرار.

هل يجب أخذ عينات من الطلبات لتقليل حجم السجلات؟

لا. سجل JSON واحد لكل طلب ليس عبئًا كبيرًا، وأخذ العينات يفسد إسناد التكلفة لكل عميل ومسار.

هل يعمل هذا مع مزودي LLM آخرين؟

نعم. أضف عمود provider مثل:

openai
anthropic
google
deepseek

ثم استخدم جدول تسعير مختلفًا لكل مزود. المخطط ولوحات التحكم تبقى نفسها. كنقطة مقارنة، راجع تسعير DeepSeek V4 API.

هل ينطبق على embeddings والصور؟

نعم، لكن مع حساب تكلفة مختلف. embeddings تُحسب عادةً حسب توكنات الإدخال. الصور تُحسب حسب عدد الصور والدقة. أضف عمودًا مثل endpoint:

chat
embeddings
image

ثم فرّع دالة حساب التكلفة حسب نوع الاستدعاء.

دليل اختبار خادم MCP: يدوي + آلي باستخدام Apidog

Yusuf Khalidd — Mon, 11 May 2026 08:56:22 +0000

منشور "Ableton Live MCP" على Show HN وصل إلى 118 نقطة و78 تعليقًا هذا الأسبوع. النمط صار مألوفًا: مطوّر يبني خادم Model Context Protocol لأداة غير متوقعة، مستخدمو Claude Desktop يجربونه، ثم تبدأ موجة "هل أبني واحدًا لـ X؟". خلال أقل من عام، انتقل MCP من تجربة مرتبطة بـ Anthropic إلى طبقة تكامل عملية للوكلاء.

جرّب Apidog اليوم

لكن النمو السريع كشف فجوة واضحة: اختبار خوادم MCP ما زال بدائيًا. تشغيل JSON-RPC يدويًا عبر stdio مناسب لتجربة "hello world"، لكنه ينهار عندما يحتوي الخادم على 12 أداة، و3 مطالبات، وتكاملات خارجية غير مستقرة. في هذا الدليل سنبني طريقة عملية لاختبار خادم MCP يدويًا، ثم تحويل نفس الاختبارات إلى مجموعة آلية في Apidog، بحيث تتعامل مع خادم MCP مثل أي API: عقد واضح، نماذج mock، وتأكّدات regression في CI.

إذا كنت تعمل على وكلاء بشكل أوسع، فاقرأ أيضًا دليل agents.md. الاتفاقيات الموجودة فيه تساعدك على توثيق عقود خادم MCP ومشاركتها مع الفريق.

باختصار

MCP هو Model Context Protocol من Anthropic: JSON-RPC 2.0 عبر stdio أو HTTP، ويكشف ثلاث بدائيات: الأدوات، الموارد، والمطالبات.
اختبار خادم MCP يعني التحقق من استجابات initialize وtools/list وtools/call وresources/read وprompts/get مقابل عقد واضح.
ابدأ يدويًا: شغّل الخادم من الطرفية، أرسل طلبات JSON-RPC، وتأكد من الشكل قبل إدخال العملاء.
انتقل إلى الأتمتة: خزّن الطلبات في Apidog، أضف تأكيدات JSONPath، ثم شغّل المجموعة في CI.
استخدم mock server في Apidog لمحاكاة واجهات API الخارجية التي يعتمد عليها خادم MCP.
يمكنك تنزيل Apidog لتجميع الطلبات، المحاكاة، وتشغيل الاختبارات في مكان واحد.

ما هو MCP عمليًا؟

مواصفات بروتوكول سياق النموذج تعرّف بروتوكول JSON-RPC 2.0 بواجهة صغيرة. العميل، مثل Claude Desktop أو Cursor أو وكيلك الخاص، يشغّل خادم MCP، ينفّذ مصافحة initialize، ثم يستدعي الأدوات أو يقرأ الموارد أو يجلب المطالبات.

أغلب الاختبارات ستدور حول هذه الاستدعاءات:

initialize: التفاوض على إصدار البروتوكول والإمكانيات.
tools/list: إرجاع الأدوات المتاحة، مع JSON Schema لوسائط كل أداة.
tools/call: استدعاء أداة باسمها وتمرير الوسائط.
resources/list وresources/read: كشف وقراءة محتوى معرّف عبر URI.
prompts/list وprompts/get: كشف قوالب المطالبات التي يستطيع العميل استخدامها.

النقل يكون غالبًا بأحد شكلين:

stdio: إطارات JSON-RPC مفصولة بأسطر جديدة عبر stdin/stdout.
HTTP قابل للتدفق: غالبًا POST / مع SSE للتدفق.

معظم الخوادم المحلية تستخدم stdio. الخوادم البعيدة تميل إلى HTTP.

سبب أهمية الاختبار بسيط: أي خطأ في شكل tools/list أو tools/call قد يكسر Claude Desktop وCursor وأي عميل MCP آخر في نفس اللحظة.

ما الذي يجب اختباره؟

غطِّ ستة محاور رئيسية.

1. امتثال البروتوكول

تأكد من أن initialize يعيد:

protocolVersion المتوقعة.
capabilities التي يدعمها الخادم فعليًا.
معلومات الخادم الأساسية إن كانت مطلوبة في تطبيقك.

مثال طلب:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. صحة المخطط

في tools/list، تحقق من أن كل أداة تحتوي على:

name
description
inputSchema

ولا تكتفِ بوجود inputSchema. تأكد أنه JSON Schema صالح، وأن الحقول المطلوبة مذكورة في required.

3. سلوك الأدوات

لكل أداة، اختبر:

مسار النجاح.
وسيطة مفقودة.
نوع غير صحيح.
فشل في API خارجي.
timeout إن كان ممكنًا.

الاستجابة الناجحة يجب أن تحتوي على content بشكل صحيح:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Weather in Tokyo: 22°C"
      }
    ]
  }
}

أما خطأ تنفيذ الأداة فيجب أن يكون نتيجة عادية مع isError: true، وليس JSON-RPC protocol error:

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Missing required argument: city"
      }
    ]
  }
}

4. الوصول إلى الموارد

اختبر أن كل URI يظهر في resources/list يمكن قراءته عبر resources/read.

وتأكد من:

نوع المحتوى.
الترميز.
pagination إن كان المورد يدعم صفحات.
السلوك عند طلب URI غير موجود.

5. عرض المطالبات

في prompts/get، تحقق من أن الاستجابة تحتوي على messages سليمة، وأن الوسائط تُحقن في الأماكن الصحيحة.

6. أوضاع الفشل

اختبر الحالات التي تحدث في الإنتاج:

API خارجي متوقف.
credentials غير صالحة.
rate limit.
timeout.
بيانات upstream بشكل غير متوقع.

الاختبار اليدوي باستخدام stdio

ابدأ بأبسط إعداد:

الطرفية.
ملف خادم MCP.
MCP Inspector أو JSON-RPC خام.

إذا لم تبنِ خادمًا بعد، استخدم البدء السريع الرسمي لـ MCP SDK في Python أو TypeScript. مثال الطقس كافٍ لبناء مجموعة اختبار أولية.

شغّل الخادم عبر المفتش:

npx @modelcontextprotocol/inspector node your-server.js

المفتش يفتح واجهة محلية تتحدث MCP مع خادمك، وتعرض الطلبات والاستجابات. استخدمه للتحقق سريعًا من:

أن الخادم يبدأ بدون أخطاء.
أن initialize ينجح.
أن tools/list يعرض الأدوات.
أن tools/call يعيد محتوى مفهومًا.

بعد ذلك، شغّل نفس التدفق يدويًا عبر stdio لالتقاط الطلبات التي ستنقلها لاحقًا إلى Apidog:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

احفظ الطلب والاستجابة. كرر ذلك مع:

tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get

في النهاية، سيكون لديك 6 إلى 12 زوجًا من الطلبات والاستجابات تمثل العقد الفعلي لخادمك.

نقاط يجب الانتباه لها أثناء الاختبار اليدوي

كتل المحتوى

نتيجة الأداة يجب أن تعيد content كمصفوفة. أمثلة صحيحة:

{
  "content": [
    {
      "type": "text",
      "text": "done"
    }
  ]
}

{
  "content": [
    {
      "type": "image",
      "data": "base64...",
      "mimeType": "image/png"
    }
  ]
}

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

أخطاء الأداة

لا تستخدم JSON-RPC error لفشل منطقي داخل الأداة. استخدم:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Upstream API failed"
    }
  ]
}

JSON-RPC error يجب أن يبقى لأخطاء البروتوكول، مثل method غير معروف أو payload غير صالح.

من اليدوي إلى الآلي: بناء مجموعة اختبار في Apidog

الاختبار اليدوي يكشف الأخطاء الواضحة. لكنه لا يجيب بسرعة على سؤال مثل:

هل التغيير الأخير كسر inputSchema للأداة السابعة؟

الحل: حوّل الطلبات التي حفظتها إلى مجموعة اختبار آلية في Apidog.

النمط العملي:

أنشئ مشروعًا.
أضف طلبات JSON-RPC.
أضف تأكيدات JSONPath.
استخدم mock server للأنظمة الخارجية.
شغّل المجموعة في CI.

1. إنشاء مشروع Apidog لخادم MCP

افتح Apidog وأنشئ مشروعًا جديدًا.

إذا كان خادم MCP لديك يعمل عبر HTTP، اضبط Base URL مباشرة على endpoint الخاص به.

إذا كان يعمل عبر stdio فقط، استخدم غلاف HTTP رقيق أثناء الاختبار. الفكرة:

Apidog يرسل HTTP request.
wrapper يستقبل JSON-RPC.
wrapper يمرره إلى خادم MCP عبر stdio.
يعيد الاستجابة إلى Apidog.

يمكنك استخدام المفتش الرسمي أو كتابة wrapper بسيط في Node.js. نفس النمط مفيد عند اختبار خدمات غير HTTP، كما في اختبار واجهة برمجة التطبيقات بدون Postman في 2026.

2. حفظ الطلبات الكنسية

أنشئ طلبًا لكل استدعاء مهم:

initialize
tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get

مثال طلب tools/call:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

احفظ نسخة لمسار النجاح ونسخًا أخرى لحالات الفشل.

مثال لمدخل غير صالح:

{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {}
  }
}

3. إضافة تأكيدات JSONPath

الهدف ليس فقط إرسال الطلب. الهدف هو التأكد من شكل الاستجابة.

تأكيدات `initialize`

أضف تأكيدات مثل:

$.result.protocolVersion يساوي الإصدار المتوقع.
$.result.capabilities موجود.
لا توجد $.error.

تأكيدات `tools/list`

تأكد من:

وجود $.result.tools.
أن $.result.tools مصفوفة.
أن عدد الأدوات أكبر من صفر.
أن كل أداة تحتوي على name.
أن كل أداة تحتوي على description.
أن كل أداة تحتوي على inputSchema.

مثال checks عملية:

$.result.tools exists
$.result.tools[0].name exists
$.result.tools[0].description exists
$.result.tools[0].inputSchema exists

تأكيدات `tools/call` لمسار النجاح

تأكد من:

$.result.isError غير موجود أو يساوي false.
$.result.content مصفوفة.
$.result.content[0].type موجود.
$.result.content[0].text يحتوي على قيمة متوقعة إن كانت الاستجابة نصية.

تأكيدات `tools/call` لمسار الفشل

لوسيطة مفقودة مثلًا، تأكد من:

$.result.isError يساوي true.
$.result.content[0].type يساوي text.
$.result.content[0].text يطابق regex ثابتًا بدل مقارنة النص الكامل.

لا تجعل الاختبار هشًا بمقارنة رسالة خطأ كاملة قد تتغير لاحقًا.

4. محاكاة واجهات API الخارجية

معظم خوادم MCP تغلف أنظمة خارجية:

Weather API
GitHub
Linear
Notion
قاعدة بيانات داخلية
منصة مراقبة

لا تجعل CI يعتمد على هذه الخدمات مباشرة. ستواجه:

rate limits.
تكلفة أعلى.
نتائج غير حتمية.
فشل عابر خارج سيطرتك.

استخدم mock server في Apidog:

عرّف endpoint الخارجي كمسار mock.
أعد JSON واقعيًا يشبه الإنتاج.
اجعل خادم MCP يقرأ Base URL من متغير بيئة.
في CI، وجّه المتغير إلى mock URL.
في الإنتاج، وجّهه إلى API الحقيقي.

مثال:

UPSTREAM_BASE_URL=https://mock.apidog.local npm test

هذا يجعل مجموعة الاختبار سريعة وحتمية. نغطي نفس الفكرة في تطوير واجهة برمجة التطبيقات القائم على العقد أولًا.

5. تشغيل المجموعة في CI

بعد حفظ الطلبات والتأكيدات، شغّلها مع كل push أو pull request.

مثال GitHub Actions:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &

      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}

بهذا، أي تغيير يكسر tools/list أو inputSchema أو سلوك أداة سيظهر قبل الدمج.

كيف تبدو تغطية اختبار جيدة؟

لخادم MCP متوسط، استخدم هذا الحد الأدنى:

طلب initialize واحد مع تأكيدات البروتوكول.
طلب tools/list واحد مع تأكيدات الشكل وJSON Schema.
من 2 إلى 4 طلبات tools/call لكل أداة:
- مسار النجاح.
- وسيطة مفقودة.
- نوع غير صالح.
- فشل upstream.
طلب resources/list.
طلب resources/read لكل عائلة موارد.
طلب prompts/list.
طلب prompts/get لكل قالب مطالبة.

لخادم يحتوي على 10 أدوات و3 موارد و4 مطالبات، قد تصل المجموعة إلى 50-70 طلبًا. هذا طبيعي. مع mock server، يجب أن تعمل المجموعة خلال ثوانٍ.

أخطاء شائعة عند اختبار خوادم MCP

تخطي `initialize`

بعض الخوادم تبني سجل الأدوات أثناء المصافحة. إذا بدأت مباشرة بـ tools/list، قد تحصل على فشل غير واقعي.

اجعل initialize أول خطوة في كل سيناريو.

التأكيد على نص الخطأ الكامل

رسائل الأخطاء تتغير. الأفضل:

أكد على isError: true.
استخدم error code إن كان موجودًا.
أو استخدم regex ثابتًا بدل مطابقة النص كاملًا.

ترك mock يبتعد عن الإنتاج

إذا كان mock يعيد شكلًا لا يعيده API الحقيقي، فالاختبارات ستنجح بينما التكامل مكسور.

حدّث fixtures من استجابات حقيقية عند كل إصدار مهم.

نسيان Streaming

خوادم MCP عبر HTTP قد تبث النتائج عبر Server-Sent Events. إن كان خادمك يستخدم SSE، فعّل دعم التدفق في الطلبات المحفوظة داخل Apidog، ثم أكد على النتيجة المجمعة.

عدم اختبار التزامن

عملاء MCP قد يرسلون عدة tools/call بالتوازي داخل agent loop. إذا كان خادمك يستخدم حالة مشتركة بدون حماية، فقد تنجح اختبارات الطلب الواحد ويفشل الإنتاج.

أضف اختبارًا يشغّل عدة استدعاءات للأداة نفسها بالتوازي.

خلط أخطاء البروتوكول مع أخطاء الأداة

فشل الأداة يجب أن يعود داخل result مع isError: true. أما JSON-RPC error فهو لفشل البروتوكول نفسه. الخلط بينهما قد يجعل Claude Desktop يغلق الاتصال. هذا شبيه بمشاكل العقود التي تظهر في تطوير منصة API القائم على العقد أولًا.

حالات استخدام واقعية

فريق بنى خادم MCP داخليًا لواجهة إدارة الحوادث اكتشف ثلاثة تراجعات في أسبوع واحد عبر تأكيدات Apidog على شكل tools/list. بدون الاختبار، كانت الأخطاء ستصل إلى كل مهندس يستخدم Claude Desktop داخل الشركة.

مطور مستقل يبني خادم MCP مفتوح المصدر لـ Notion استخدم mock server في Apidog لتشغيل الاختبارات في CI بدون استهلاك rate limits من Notion. المجموعة تعمل على كل pull request، وتستخدم fixtures مخزنة في المستودع.

فريق منصة يدير 14 خادم MCP داخليًا أنشأ workspace مشتركة في Apidog لعقود الخوادم. كل خادم جديد يبدأ من مجموعة اختبار أساسية، والمراجعون يقارنون تغييرات المخطط قبل الدمج.

فريق آخر يبني خادم MCP لمنصة مراقبة داخلية يستخدم environments في Apidog لتشغيل نفس المجموعة ضد التطوير والإنتاج، بدون إعادة كتابة الطلبات.

الخاتمة

MCP أصبح شائعًا بسرعة، لكن اختبار خوادمه ما زال غالبًا يدويًا وهشًا. لا تنتظر أن ينضج النظام البيئي. تعامل مع خادم MCP كواجهة API حقيقية:

صمّم عقدًا واضحًا.
اختبر initialize وtools/list وtools/call.
غطِّ الموارد والمطالبات.
حاكِ الأنظمة الخارجية.
شغّل التأكيدات في CI.

الخلاصة العملية:

خادم MCP هو JSON-RPC API؛ اختبره بنفس جدية REST API.
ابدأ بالمفتش الرسمي وطلبات stdio الخام.
انقل الطلبات إلى Apidog.
أضف تأكيدات JSONPath.
استخدم mock server للـ upstream APIs.
شغّل المجموعة مع كل push.

الخطوة التالية: افتح Apidog، أنشئ مشروعًا، الصق طلبات JSON-RPC التي التقطتها، أضف تأكيدات tools/list، ثم شغّل المجموعة. خلال ساعة ستعرف إن كان عقد خادم MCP لديك جاهزًا للشحن.

الأسئلة الشائعة

ما هو MCP؟

MCP، أو Model Context Protocol، هو مواصفة مفتوحة من Anthropic لكيفية استدعاء عملاء الذكاء الاصطناعي للأدوات والموارد والمطالبات الخارجية. يعتمد على JSON-RPC 2.0 عبر stdio أو HTTP قابل للتدفق. المواصفات الكاملة لـ MCP منشورة على modelcontextprotocol.io.

هل يمكنني اختبار خادم MCP بدون غلاف HTTP؟

نعم. المفتش الرسمي لـ MCP يتحدث stdio مباشرة ويوفر واجهة للاختبار اليدوي. للاختبار الآلي في Apidog، استخدم HTTP wrapper رقيقًا أثناء CI فقط.

كيف أحاكي واجهات API الخارجية التي يستدعيها خادم MCP؟

عرّف كل endpoint خارجي كـ mock في Apidog، ثم وجّه إعدادات خادم MCP إلى mock URL أثناء الاختبارات. في الإنتاج، استخدم URL الحقيقي. نفس النمط موضح في أدوات اختبار واجهة برمجة التطبيقات لمهندسي ضمان الجودة.

ماذا عن نتائج الأدوات المتدفقة؟

خوادم MCP عبر HTTP قد تستخدم Server-Sent Events. يدعم Apidog SSE في الطلبات المحفوظة؛ فعّل التدفق في إعدادات الطلب، ثم أكد على النتيجة بعد تجميعها.

هل يجب اختبار إصدار البروتوكول؟

نعم. ثبّت protocolVersion في initialize وأضف تأكيدًا عليه. عدم التطابق قد يسبب مشاكل توافق صامتة مع العملاء.

هل أختبر خادمي مقابل Claude Desktop الحقيقي؟

نعم، مرة واحدة على الأقل قبل كل إصدار. لكن لا تجعله حلقة regression الأساسية. استخدم Apidog للاختبارات الآلية، وClaude Desktop لاختبار smoke نهائي.

أين أجد أمثلة لخوادم MCP حقيقية؟

راجع مستودع خوادم MCP الرسمي. يحتوي على تطبيقات مرجعية لأنظمة الملفات، GitHub، Slack، Postgres، وغيرها. اقرأ تعريفات الأدوات لفهم شكل MCP الجيد.

ما هو Maigret: ماسح OSINT لا يتعطل

Yusuf Khalidd — Mon, 11 May 2026 06:11:50 +0000

معظم أدوات استخبارات المصادر المفتوحة (OSINT) تتقادم بسرعة: تتغير صفحات الويب، تنتقل المواقع إلى نقاط نهاية جديدة، تظهر اختبارات Captcha أقوى، ثم تتعطل الأداة بعد عام أو عامين. يُعد Maigret استثناءً عمليًا: يعمل منذ سنوات، يدعم أكثر من 3000 موقع، ويوفر حزمة بايثون، وبوت تيليجرام، وواجهة ويب. الأهم للمهندسين أن بنيته الداخلية تقدم نموذجًا جيدًا لبناء ماسح لا ينهار عند تغير المواقع.

جرّب Apidog اليوم

هذا الدليل موجه للمهندسين. سنفكك ما يفعله Maigret، متى يكون استخدامه مشروعًا، كيف تعمل قاعدة توقيعات المواقع، وكيف يمكن نقل الأنماط نفسها إلى اختبار واجهات برمجة التطبيقات باستخدام Apidog.

إذا لم تكن قد قرأته بعد، فإن منشورنا اختبار واجهات برمجة التطبيقات بدون Postman في عام 2026 يغطي أفكار مطابقة الأنماط واكتشاف الانحراف في سياق اختبار API.

خلاصة القول TL;DR

يستخدم Maigret اسم مستخدم واحدًا للبحث عن حسابات عامة عبر أكثر من 3000 موقع.
يعتمد على قاعدة بيانات توقيعات للمواقع، لا على منطق مبرمج يدويًا لكل حالة.
يميز بين “الحساب موجود” و“الحساب غير موجود” باستخدام عدة إشارات: نصوص وجود، نصوص غياب، رؤوس، وأنماط URL.
الاستخدام المشروع يشمل الصحافة الاستقصائية، استعادة الحسابات، البحث عن المفقودين بموافقة، مراقبة إساءة استخدام العلامة التجارية، واختبارات الاختراق المرخصة.
استخدامه على أشخاص دون موافقة أو أساس قانوني قد يتحول إلى تحرش أو مطاردة رقمية.
أنماطه المعمارية مفيدة جدًا لاختبار API: توقيعات، تأكيدات متعددة الإشارات، اختبارات انحدار، واكتشاف انحراف.
يمكنك تطبيق الفكرة نفسها في Apidog عبر تعريف توقعات دقيقة لكل endpoint وتشغيلها دوريًا.

ما هو Maigret وما ليس هو

Maigret أداة بايثون مرخصة بموجب MIT ويصونها soxoj. يصفها README بأنها أداة “لجمع ملف كامل عن شخص ما باستخدام اسم المستخدم من أكثر من 3000 موقع”.

الاستخدام الأساسي:

pip install maigret
maigret username

يشغّل الأمر بحثًا عبر المواقع الموجودة في قاعدة البيانات، ثم ينتج تقريرًا بالحسابات العامة التي تم العثور عليها.

ثلاث نقاط مهمة:

Maigret يستخدم البيانات العامة فقط.

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

يستخدمه صحفيون، متطوعو بحث عن مفقودين، فرق مكافحة احتيال، فرق حماية علامة تجارية، وفرق red-team ضمن نطاق مصرح به.
يمكن إساءة استخدامه.

تشغيله على فرد خاص دون موافقة أو مبرر قانوني قد يخالف قوانين الملاحقة والتحرش في عدة ولايات قضائية.

سنركز هنا على الهندسة وأنماط الاختبار القابلة لإعادة الاستخدام، لا على استهداف الأشخاص.

التثبيت والتشغيل السريع

للتجربة محليًا:

python --version
pip install maigret
maigret example_user

لتشغيل فحص أوسع يشمل جميع المواقع المتاحة:

maigret example_user -a

لتحديث قاعدة بيانات المواقع قبل تشغيل جاد:

maigret --update
maigret example_user -a

لإخراج تقرير بصيغة HTML أو JSON:

maigret example_user --html
maigret example_user --json

الفكرة الهندسية هنا ليست الأمر نفسه، بل طريقة تصميم النظام: قاعدة توقيعات قابلة للتحديث، محرك فحص عام، ومخرجات قابلة للتحليل.

قاعدة بيانات توقيعات المواقع

أقوى فكرة في Maigret هي أنه لا يكتب منطقًا خاصًا لكل موقع داخل الكود. بدلًا من ذلك، يصف كل موقع داخل قاعدة بيانات JSON.

كل توقيع يجيب عن أسئلة مثل:

ما رابط الملف الشخصي؟
كيف يبدو الرد عندما يكون الحساب موجودًا؟
كيف يبدو الرد عندما لا يكون الحساب موجودًا؟
ما النصوص التي تؤكد الوجود؟
ما النصوص التي تؤكد الغياب؟
هل يحتاج الموقع إلى رؤوس HTTP خاصة؟
هل يطبق الموقع Captcha أو rate limit؟
ما البيانات العامة التي يمكن استخراجها من الصفحة؟

مثال مبسط لفكرة التوقيع:

{
  "name": "ExampleSite",
  "urlMain": "https://example.com",
  "url": "https://example.com/{username}",
  "presenseStrs": ["Profile", "@{username}"],
  "absenceStrs": ["User not found", "This profile does not exist"],
  "headers": {
    "User-Agent": "Mozilla/5.0"
  },
  "tags": ["social", "global"]
}

ملاحظة: المثال للتوضيح وليس توقيعًا رسميًا من Maigret.

هذا النمط هو نفسه الذي تحتاجه في اختبار API. بدلًا من كتابة اختبارات مبعثرة داخل ملفات كثيرة، عرّف “توقيع” كل endpoint:

{
  "endpoint": "GET /users/{id}",
  "expectedStatus": 200,
  "requiredFields": ["id", "email", "createdAt"],
  "forbiddenFields": ["password", "token"],
  "contentType": "application/json"
}

ثم شغّل محرك اختبار عام يقرأ هذه التوقيعات ويتحقق منها. هذا هو جوهر تطوير API المبني على العقد، وقد تناولناه أيضًا في تطوير API المبني على العقد أولاً ودليل اختبار خادم MCP.

كيف يميز Maigret بين وجود الحساب وعدم وجوده

الطريقة الساذجة هي:

GET https://example.com/user/<username>
إذا عاد 200 => الحساب موجود
إذا عاد 404 => الحساب غير موجود

لكن الويب الحقيقي لا يعمل بهذه البساطة. كثير من المواقع تعيد 200 OK حتى عندما لا يكون المستخدم موجودًا، وتعرض رسالة مثل:

User not found

أو تعيد صفحة عامة، أو Captcha، أو redirect.

لذلك يستخدم Maigret عدة إشارات:

قالب URL.
نصوص يجب أن تظهر عند وجود الحساب.
نصوص يجب أن تظهر عند غياب الحساب.
أحيانًا regex لاستخراج اسم المستخدم أو حقول إضافية.
رؤوس HTTP مخصصة.
تصنيف الموقع حسب الفئة أو البلد.

المنطق العملي يكون قريبًا من:

def classify_response(body, presence_strs, absence_strs):
    has_presence = all(s in body for s in presence_strs)
    has_absence = any(s in body for s in absence_strs)

    if has_presence and not has_absence:
        return "found"

    if has_absence:
        return "not_found"

    return "unknown"

النقطة المهمة: رمز الحالة وحده لا يكفي.

في اختبار API، افعل الشيء نفسه. لا تكتفِ بـ 200 OK. تحقق من:

status code
content type
الحقول المطلوبة
الحقول الممنوعة
شكل الخطأ
headers المهمة
قيم business-critical

مثال assertion منطقي:

pm.test("user response contract", function () {
  pm.response.to.have.status(200);

  const json = pm.response.json();

  pm.expect(json).to.have.property("id");
  pm.expect(json).to.have.property("email");
  pm.expect(json).to.not.have.property("password");
});

في Apidog، يمكنك تطبيق الفكرة نفسها عبر تأكيدات status code، body، schema، والحقول المطلوبة في الطلب نفسه.

البحث المتكرر واستخراج المعلومات

بعد أن يجد Maigret حسابًا، لا يتوقف عند “تم العثور على الحساب”. يقوم بخطوتين إضافيتين:

استخراج معلومات عامة من صفحة الملف الشخصي

مثل اسم ظاهر، روابط، أسماء مستخدمين أخرى، أو معرفات عامة.
إعادة استخدام المعرفات المكتشفة في جولة بحث جديدة

مثلًا: اسم مستخدم يؤدي إلى حساب، الحساب يعرض اسمًا آخر، الاسم الآخر يقود إلى خدمة أخرى.

هذا يسمى بحثًا متكررًا أو recursive enrichment.

تصور مبسط:

username
  -> profile on Site A
      -> linked username on Site B
          -> profile on Site B
              -> public email or alias

في سياق API، النمط نفسه مفيد:

GET /users/123
  -> returns organizationId
      -> GET /organizations/{organizationId}
          -> returns planId
              -> GET /plans/{planId}

عندما تكتشف حقلًا جديدًا في استجابة API، لا تتجاهله. اسأل:

هل هو موثق؟
هل يشير إلى endpoint آخر؟
هل يحتاج إلى اختبار؟
هل يجب إضافته إلى contract؟
هل كسره سيؤثر على عميل آخر؟

التعامل مع Captcha وRate Limits

Maigret لا يحاول كسر دفاعات المواقع. يتعامل مع القيود بلطف، ويستخدم إشارات الاستجابة لاكتشاف:

rate limit
Captcha
حظر Tor أو I2P
الحاجة إلى User-Agent معين
headers مثل Retry-After

استراتيجياته تشمل:

تدوير User-Agent.
احترام رؤوس retry.
استخدام نطاقات جوال أو صفحات مبسطة عندما تكون متاحة.
تسجيل الحالة كـ Captcha detected بدلًا من محاولة تجاوز دفاع قوي.

هذا درس مهم لاختبار API.

لا تبنِ مشغّل اختبارات يضرب API بلا حدود. صممه ليحترم:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

مثال تعامل بسيط:

async function requestWithBackoff(fetchFn) {
  const response = await fetchFn();

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get("Retry-After") || 60);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchFn();
  }

  return response;
}

هذا يحمي اختباراتك من حظر IP الفريق، ويحافظ على سلوك متوافق مع شروط الخدمة.

مشكلة انحراف التوقيع

أي قاعدة تضم آلاف التوقيعات ستنحرف مع الوقت. المواقع تغير:

بنية URL.
نصوص صفحات الخطأ.
شكل الملف الشخصي.
سياسات Captcha.
أسماء الحقول.
العلامة التجارية بالكامل.

إذا لم تحدّث التوقيع، تحصل على:

false positive: يظن أن الحساب موجود وهو غير موجود.
false negative: يفشل في العثور على حساب موجود.
unknown results كثيرة بلا فائدة.

يعالج Maigret ذلك عبر:

تحديث تلقائي من مستودع GitHub المركزي كل 24 ساعة.
مساهمات المجتمع عبر pull requests.
خيار --update.
اختبارات مدمجة تتحقق من صحة التوقيعات مقابل أسماء مستخدمين معروفة.

هذا الجزء هو الأهم لمهندسي API: كل contract يحتاج إلى اختبار انحدار دوري.

في API، احفظ استجابة معروفة وصحيحة:

{
  "id": "usr_123",
  "email": "dev@example.com",
  "createdAt": "2026-01-01T00:00:00Z"
}

ثم شغّل اختبارًا دوريًا يتحقق من أن endpoint ما زال يعيد نفس الشكل:

const requiredFields = ["id", "email", "createdAt"];

for (const field of requiredFields) {
  if (!(field in responseBody)) {
    throw new Error(`Missing field: ${field}`);
  }
}

يدعم Apidog هذا النمط عبر حفظ الطلبات، تعريف التأكيدات، تشغيلها دوريًا، ومقارنة النتائج لاكتشاف الانحراف. يغطي دليل DeepSeek V4 API مثالًا عمليًا على التعامل مع API لبائع محدد.

وضع الملخص بالذكاء الاصطناعي

توفر Maigret علامة:

maigret username --ai

تستخدم هذه العلامة نقطة نهاية LLM متوافقة مع OpenAI لتلخيص النتائج. أنت توفر مفتاح API، وMaigret يرسل النتائج الخام ليحصل على ملخص قابل للقراءة.

النمط الهندسي هنا مهم:

القواعد الحتمية تقرر هل الحساب موجود أم لا.
النموذج اللغوي لا يقرر الحقيقة.
النموذج يلخص فقط نتائج تم حسابها مسبقًا.

هذا يقلل الهلوسة. النموذج يعمل كـ postprocessor، لا كـ judge.

في مراقبة API، يمكنك تطبيق البنية نفسها:

شغّل تأكيدات حتمية في Apidog.
اجمع نتائج التشغيل.
أرسل الملخص إلى LLM لصياغة تقرير Slack أو بريد إلكتروني.
لا تجعل LLM يقرر النجاح أو الفشل.

ناقشنا هذه الفكرة في استخدام الحاسوب مقابل واجهات برمجة التطبيقات المنظمة: الطبقة المنظمة يجب أن تأتي أولًا.

حالات الاستخدام المشروعة

استخدم Maigret فقط في سياقات واضحة ومصرح بها. أمثلة مقبولة:

1. استعادة حساباتك الشخصية

إذا استخدمت اسم مستخدم قديمًا منذ سنوات، يمكنك البحث عن الحسابات العامة المرتبطة به قبل إغلاقها أو تحديث إعدادات الخصوصية.

maigret old_username -a

2. مراقبة إساءة استخدام العلامة التجارية

يمكن للشركات البحث عن أسماء منتجاتها أو علاماتها لاكتشاف حسابات انتحال.

maigret brand_name -a

3. البحث عن المفقودين بموافقة

تستخدم بعض فرق البحث والإنقاذ أدوات OSINT بموافقة الأسرة وبالتنسيق مع جهات إنفاذ القانون.

4. اختبارات الاختراق المرخصة

ضمن عقد red-team أو pentest، يمكن استخدام Maigret لتحديد سطح التعرض العام للمؤسسة.

القاعدة هنا: النطاق مكتوب ومصرح به.

5. الصحافة الاستقصائية

يستخدم الصحفيون أدوات OSINT ضمن مراجعة تحريرية وقانونية، خصوصًا عند التحقيق في احتيال، جرائم منظمة، أو قضايا مصلحة عامة.

ما لا يدخل ضمن الاستخدام المشروع:

البحث عن شخص بدافع الفضول.
مراقبة شريك سابق.
بناء قاعدة بيانات عن أشخاص لم يوافقوا.
استهداف أفراد خاصين دون أساس قانوني.

أنماط من Maigret يمكنك تطبيقها على اختبار API

1. استخدم توقيعات كبيانات

بدلًا من كتابة اختبار مخصص لكل endpoint، عرّف السلوك المتوقع كبيانات.

{
  "method": "GET",
  "path": "/orders/{id}",
  "expectedStatus": 200,
  "requiredFields": ["id", "status", "total"],
  "forbiddenFields": ["internalNotes"]
}

هذا يسهل إضافة endpoints جديدة دون إعادة بناء نظام الاختبار.

2. لا تثق في status code وحده

اختبر عدة إشارات:

status code + content-type + schema + required fields + forbidden fields

مثال:

expect(response.status).toBe(200);
expect(response.headers["content-type"]).toContain("application/json");
expect(body).toHaveProperty("id");
expect(body).not.toHaveProperty("password");

3. حدّث التوقيعات مركزيًا

كما يحدّث Maigret قاعدة المواقع من GitHub، يجب أن تمتلك مصدرًا مركزيًا لعقود API. مشاريع Apidog تدعم التعاون والمزامنة، وهذا يقلل تشتت العقود بين الفرق.

راجع أيضًا اختبار API بدون Postman.

4. شغّل اختبارات الانحراف دوريًا

لا تنتظر أن يكتشف المستخدمون تغيرًا في API. شغّل اختبارات مجدولة:

كل ساعة / كل يوم / قبل النشر / بعد النشر

وتحقق من:

هل تغير schema؟
هل اختفى حقل؟
هل تغير نوع البيانات؟
هل تغير شكل الخطأ؟
هل زاد زمن الاستجابة؟

5. استخدم LLM للتلخيص فقط

اجعل القواعد الحتمية تقرر:

pass / fail

ثم استخدم LLM لصياغة تقرير مثل:

فشل اختبار GET /orders/{id} لأن الحقل total لم يعد موجودًا.
بدأ الفشل في تشغيل 02:10 UTC.

لا تجعل النموذج يقرر صحة العقد.

المزالق الشائعة عند تشغيل Maigret

افتراض أن التشغيل الافتراضي كامل

التشغيل الافتراضي لا يفحص كل شيء دائمًا. إذا كنت تحتاج إلى فحص أوسع، استخدم:

maigret username -a

لكن توقع وقت تشغيل أطول.

تجاهل tags

يمكن تضييق البحث حسب الفئة أو البلد باستخدام:

maigret username --tags social

هذا مفيد عندما يكون النطاق الجغرافي أو نوع المواقع مهمًا.

تخطي التحديث

قاعدة توقيعات قديمة تعني نتائج غير موثوقة. قبل أي فحص جاد:

maigret --update

تفسير حظر Tor كدليل

بعض المواقع تحظر Tor بالكامل. إذا فشل الوصول عبر Tor، لا تستنتج شيئًا عن وجود الحساب.

تصديق كل حقل مستخرج

Maigret يقرأ ما تعرضه الصفحة. الصفحات العامة يمكن تزويرها. اعتبر النتائج أدلة تحتاج تحققًا، لا إثباتًا نهائيًا.

حالات استخدام واقعية

شركة استشارات أمنية تستخدم Maigret في بداية كل عملية red-team مرخصة لتقديم صورة أولية عن سطح التعرض العام للعميل.

محقق احتيال مستقل يستخدم:

maigret target_username -a --ai

لتحويل نتائج آلاف المواقع إلى ملخص قصير لعميل غير تقني. البحث نفسه حتمي، والذكاء الاصطناعي فقط يصيغ التقرير.

فريق هندسي يستخدم الأنماط نفسها داخل اختبارات API الخاصة به: قاعدة توقيعات، تشغيل دوري، واكتشاف انحراف عبر 200 خدمة مصغرة. التنفيذ داخل Apidog، لكن المبادئ هي مبادئ Maigret نفسها.

الخاتمة

Maigret ليس مجرد أداة OSINT. هو مثال عملي على بناء نظام يتحمل تغير آلاف الأسطح الخارجية: توقيعات قابلة للتحديث، تأكيدات متعددة الإشارات، اكتشاف انحراف، ومعالجة LLM لاحقة لا تتحكم في القرار.

خمسة دروس قابلة للتطبيق:

عرّف السلوك المتوقع كبيانات، لا ككود متشعب.
استخدم عدة إشارات للحكم، لا status code فقط.
شغّل اختبارات دورية ضد fixtures معروفة.
تعامل مع الانحراف كحالة طبيعية، لا كاستثناء.
استخدم LLM للتلخيص، وليس للحكم على صحة النتائج.

الخطوة التالية: اقرأ تنسيق قاعدة بيانات مواقع Maigret، ثم افتح Apidog وصمم endpoint واحدًا بالطريقة نفسها: توقيع واضح، تأكيدات متعددة، واستجابة محفوظة لاكتشاف الانحراف. هذا الانضباط يدفع ثمنه عندما يغير مزود خارجي اسم حقل في الثانية صباحًا وتلتقطه اختباراتك قبل المستخدمين.

الأسئلة الشائعة

هل استخدام Maigret قانوني؟

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

هل يعمل Maigret بدون بايثون؟

الحزمة الرسمية تتطلب Python 3.10+. يوجد أيضًا بوت تيليجرام وخيارات تشغيل سحابية لمن لا يريد تثبيتًا محليًا.

ما مدى دقة رقم 3000 موقع؟

قاعدة البيانات تسرد أكثر من 3000 إدخال، لكن ليس كل موقع يكون فعالًا في كل لحظة. التحديثات المجتمعية والتحديث التلقائي يحافظان على أكبر قدر ممكن من الدقة.

ماذا يضيف وضع الذكاء الاصطناعي؟

علامة --ai تلخص النتائج الحتمية باستخدام LLM متوافق مع OpenAI. لا تغير عملية البحث ولا تقرر صحة النتائج. تحتاج إلى مفتاح API خاص بك.

هل يمكن استخدام Maigret في CI؟

لتحقيقات OSINT، غالبًا لا؛ لأنها تفاعلية وتعتمد على سياق قانوني وأخلاقي. لكن أنماطه المعمارية مناسبة جدًا لـ CI في اختبار API: توقيعات، اكتشاف انحراف، وتشغيل مجدول. يدعم Apidog هذه الأنماط بشكل أصلي.

كيف يختلف Maigret عن Sherlock؟

Sherlock أقدم وأبسط. Maigret يضيف استخراج معلومات، بحثًا متكررًا، معالجة Captcha جزئية، وضع تلخيص بالذكاء الاصطناعي، وقاعدة مواقع أغنى. كلاهما مرخص بموجب MIT ويستحقان المعرفة.

أين أبلغ عن توقيع قديم؟

استخدم GitHub Issues أو Pull Requests في مستودع Maigret. عادةً الأفضل فتح طلب سحب صغير يحدّث توقيع موقع واحد بوضوح.

حل مشكلة خطأ "تكوين مؤسسة 3p مخصص غير صالح" في كود Claude

Yusuf Khalidd — Mon, 11 May 2026 03:32:53 +0000

إذا حاولت توجيه Claude Code إلى DeepSeek V4 أو OpenRouter أو أي مزود نموذج طرف ثالث آخر وظهر لك الخطأ Invalid custom3p enterprise config، فالمشكلة غالبًا ليست في النموذج نفسه، بل في تهيئة Claude Code: عنوان URL الأساسي، نوع مفتاح المصادقة، ملف settings.json، أو إعدادات المؤسسة.

جرّب Apidog اليوم

في هذا الدليل العملي ستجد معنى custom3p، أكثر الأسباب شيوعًا للخطأ، وكيفية إصلاح كل سبب بخطوات وأمثلة تهيئة قابلة للاستخدام مع OpenRouter وLiteLLM وvLLM.

خلاصة سريعة

Invalid custom3p enterprise config يعني أن Claude Code لم يستطع التحقق من صحة تهيئة مزود خارجي.

custom3p هو الاسم الداخلي في Claude Code لأي نقطة نهاية API غير تابعة لـ Anthropic يتم تفعيلها عبر:

ANTHROPIC_BASE_URL

ابدأ دائمًا بهذه الفحوصات:

احذف /v1 من نهاية ANTHROPIC_BASE_URL.
استخدم متغير المصادقة الصحيح:
- ANTHROPIC_AUTH_TOKEN للـ Bearer token.
- ANTHROPIC_API_KEY لرأس x-api-key.
تحقق من صحة ~/.claude/settings.json.
تأكد أن الإعداد الأولي لـ Claude Code مكتمل.
تأكد أن بوابتك تمرر الرؤوس المطلوبة.
تحقق من عدم وجود سياسة مؤسسة تمنع المزود المخصص.

ماذا يعني `custom3p`؟

يوجه Claude Code الطلبات عبر عدة أوضاع:

الوضع	كيف يتم تفعيله
Anthropic API الافتراضي	بدون تجاوز
Amazon Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`
Google Vertex AI	`CLAUDE_CODE_USE_VERTEX=1`
Microsoft Foundry	`CLAUDE_CODE_USE_FOUNDRY=1`
طرف ثالث مخصص	`ANTHROPIC_BASE_URL` يشير إلى مزود آخر

عندما تضبط ANTHROPIC_BASE_URL على مضيف غير تابع لـ Anthropic مثل OpenRouter أو LiteLLM أو vLLM أو بوابة داخلية، يتعامل Claude Code مع هذا المسار داخليًا باسم custom3p.

قبل إرسال أول طلب، يجري Claude Code تحققًا من التهيئة. إذا فشل، يظهر الخطأ:

Invalid custom3p enterprise config

هذا خطأ تهيئة، وليس حظرًا سياسيًا أو رفضًا تلقائيًا لاستخدام مزود خارجي.

لماذا يظهر هذا الخطأ الآن؟

بعد قيود Anthropic في أبريل 2026 على أدوات كانت تزيف معرف عميل Claude Code للوصول إلى اشتراكات Pro وMax، بدأ مطورون كثيرون باستخدام دعم الطرف الثالث الرسمي في Claude Code لتوجيه الجلسات عبر مزودين أرخص.

على سبيل المثال، وثّق أحد المواضيع استخدام DeepSeek V4 Pro عبر OpenRouter بتكلفة أقل بكثير من Anthropic. كما ظهرت أدوات مثل DeepClaude لتبسيط الإعداد.

المشكلة أن دعم الطرف الثالث الرسمي يتطلب تهيئة دقيقة. خطأ صغير في URL أو المصادقة أو JSON يكفي لإظهار:

Invalid custom3p enterprise config

السبب 1: وجود `/v1` زائدة في `ANTHROPIC_BASE_URL`

هذا هو السبب الأكثر شيوعًا.

Claude Code يضيف تلقائيًا:

/v1/messages

إلى عنوانك الأساسي. لذلك إذا وضعت /v1 بنفسك، يصبح المسار النهائي:

/v1/v1/messages

وغالبًا تحصل على 404.

خطأ

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api/v1"

export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com/v1"

صحيح

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api"

export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com"

اختبار سريع

شغّل:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  "${ANTHROPIC_BASE_URL}/v1/messages" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'

التفسير:

200: المسار صحيح والطلب نجح.
400: المسار موجود لكن الطلب غير مكتمل أو غير مطابق.
404: غالبًا لديك مشكلة /v1 مكررة أو مسار خاطئ.

السبب 2: استخدام متغير المصادقة الخاطئ

Claude Code يدعم طريقتين للمصادقة:

المتغير	يرسل كـ	الاستخدام
`ANTHROPIC_API_KEY`	رأس `x-api-key`	بوابات تتوقع مفتاح API بأسلوب Anthropic
`ANTHROPIC_AUTH_TOKEN`	رأس `Authorization: Bearer`	LiteLLM وOpenRouter وبوابات OAuth-like

OpenRouter

OpenRouter يتوقع Bearer token، لذلك استخدم:

export ANTHROPIC_AUTH_TOKEN="sk-or-your-openrouter-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

لا تستخدم ANTHROPIC_API_KEY هنا إلا إذا كانت بوابتك تدعمه صراحة.

LiteLLM

export ANTHROPIC_AUTH_TOKEN="sk-litellm-your-virtual-key"
export ANTHROPIC_BASE_URL="https://your-litellm-server:4000"

vLLM أو بوابة تتوقع `x-api-key`

export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://your-vllm-server"

إذا لم تكن متأكدًا، راجع وثائق البوابة لمعرفة الرأس المطلوب.

السبب 3: ملف `settings.json` غير صالح

إذا كنت تضع التهيئة في:

~/.claude/settings.json

فأي خطأ JSON يمنع Claude Code من قراءة الإعدادات.

خطأ: فاصلة زائدة

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-key",
  }
}

خطأ: علامات اقتباس ذكية

{
  "env": {
    “ANTHROPIC_BASE_URL”: “https://openrouter.ai/api”
  }
}

صحيح

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key"
  }
}

تحقق من الملف

باستخدام Python:

python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json')))" && echo "Valid JSON"

أو باستخدام jq:

jq . ~/.claude/settings.json

إذا فشل التحليل، أصلح JSON قبل تشغيل Claude Code.

السبب 4: تثبيت جديد لم يكمل الإعداد الأولي

في التثبيتات الجديدة، يتحقق Claude Code من:

~/.claude.json

ويبحث عن:

"hasCompletedOnboarding": true

إذا لم تكن موجودة، قد يتجاهل إعدادات الطرف الثالث ويحاول استخدام تدفق المصادقة الافتراضي.

تحقق من الحالة

cat ~/.claude.json | python3 -m json.tool 2>/dev/null | grep hasCompletedOnboarding

الإصلاح

أضف أو عدّل الملف:

{
  "hasCompletedOnboarding": true,
  "primaryApiKey": "sk-placeholder"
}

primaryApiKey هنا قيمة مؤقتة لتجاوز فحص التنسيق. سيتم تجاوزها بتهيئة المزود الخارجي.

بعد ذلك أعد تشغيل Claude Code.

السبب 5: البوابة لا تمرر الرؤوس المطلوبة

Claude Code يرسل رؤوسًا إضافية أثناء التحقق من التهيئة، ومنها:

anthropic-beta
anthropic-version
X-Claude-Code-Session-Id

إذا كانت بوابتك أو nginx أو proxy يحذف هذه الرؤوس، قد يفشل التحقق.

إعداد nginx

location /v1/ {
  proxy_pass http://backend;
  proxy_set_header anthropic-beta $http_anthropic_beta;
  proxy_set_header anthropic-version $http_anthropic_version;
  proxy_set_header X-Claude-Code-Session-Id $http_x_claude_code_session_id;
}

في LiteLLM، هذا مدعوم افتراضيًا في الإصدارات الحديثة مثل v1.82.9+.

حل بديل

إذا لم تستطع تمرير رأس anthropic-beta:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

هذا يعطل بعض الميزات التجريبية، لكنه يسمح بتشغيل حلقة الوكيل الأساسية.

السبب 6: سياسة المؤسسة تمنع التهيئة

إذا كنت ضمن خطة Claude Teams أو Enterprise، قد تكون هناك إعدادات مُدارة تتجاوز إعداداتك المحلية.

تحقق من وجودها:

ls ~/.claude/managed-settings.json 2>/dev/null && echo "تم العثور على إعدادات مُدارة"

أو من داخل Claude Code:

/status

إذا كانت الإعدادات المُدارة نشطة، اطلب من المسؤول أحد الخيارات التالية:

السماح بنطاق بوابتك في قائمة عناوين URL الأساسية.
إضافة نماذج البوابة إلى availableModels.
إعفاؤك من قيود ANTHROPIC_BASE_URL.

في macOS، قد توجد الإعدادات المُدارة في:

/Library/Application Support/ClaudeCode/managed-settings.json

تهيئات جاهزة للعمل

Claude Code + OpenRouter + DeepSeek V4 Pro

ضع التالي في:

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-pro"
  }
}

تجاوز أسماء النماذج مهم لأن Claude Code قد يستمر في طلب:

claude-sonnet-4-6

حتى بعد تغيير ANTHROPIC_BASE_URL.

ملاحظة: لا ينفذ OpenRouter كامل مواصفة تدفق Anthropic لاستدعاءات الأدوات في كل الحالات. قد تعمل الحلقة الأساسية، لكن بعض سلاسل الأدوات المعقدة قد تواجه مشكلات. تابع حالة توافق OpenRouter للتحديثات.

Claude Code + LiteLLM

مثال config.yaml لـ LiteLLM:

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: deepseek/deepseek-v4
      api_key: "sk-your-deepseek-key"
  - model_name: claude-opus-4-7
    litellm_params:
      model: deepseek/deepseek-v4-pro
      api_key: "sk-your-deepseek-key"

ثم في ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-your-key"
  }
}

بهذا الشكل، يرسل Claude Code اسم نموذج Claude، ويقوم LiteLLM بتحويله إلى النموذج الفعلي.

Claude Code + vLLM محلي

ابدأ vLLM:

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --dtype auto \
  --api-key local-key \
  --port 8000

ثم اضبط Claude Code:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="local-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-ai/DeepSeek-V3"

راجع أيضًا توثيق vLLM مع Claude Code.

تصحيح الخطأ عمليًا

شغّل Claude Code بوضع التصحيح:

claude --debug 2>&1 | head -100

ابحث عن:

Sending request to: لمعرفة URL النهائي.
Response status: لمعرفة كود HTTP.
enterprise config error: لمعرفة سبب فشل التحقق.

اختبر الطلب يدويًا:

curl -v -X POST "${ANTHROPIC_BASE_URL}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: max-tokens-3-5-sonnet-2024-07-15" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "hi"}]
  }'

إذا حصلت على:

401 أو 403: مشكلة مصادقة.
404: مشكلة URL.
422: مشكلة تنسيق الطلب أو النموذج.
200: البوابة تعمل، وراجع اختلافات رؤوس Claude Code في وضع --debug.

اختبار واجهات API باستخدام Apidog

عند تصحيح تكاملات مزودي الطرف الثالث، يساعدك Apidog على فحص الطلبات والاستجابات التي تمر عبر بوابة LLM الخاصة بك.

أنشئ مجموعة لنقطة النهاية:

/v1/messages

ثم أضف هذه الرؤوس كمتغيرات على مستوى المجموعة:

anthropic-version
anthropic-beta
Authorization

بهذا يمكنك اختبار بوابات مختلفة بتغيير المتغيرات بدل تعديل كل طلب يدويًا.

هذا مفيد خصوصًا عند التحقق من تمرير الرؤوس التي قد تسبب Invalid custom3p enterprise config.

إعدادات Claude Code مفيدة

تعطيل اعتماديات رؤوس beta

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

استخدمه عندما لا تمرر بوابتك الرؤوس المخصصة. ستفقد بعض الميزات التجريبية، لكن الحلقة الأساسية ستعمل.

اكتشاف النماذج من البوابة

من Claude Code v2.1.129:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

يستعلم Claude Code عن:

/v1/models

ويضيف النماذج المكتشفة إلى منتقي /model.

ملاحظة: يضيف عادةً النماذج التي تبدأ بـ claude أو anthropic. لنماذج مثل DeepSeek، استخدم:

export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4-pro"

إضافة نموذج مخصص إلى المنتقي

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek/deepseek-v4-pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="أرخص بـ 17 مرة من Claude Opus"

سيظهر النموذج في منتقي:

/model

أدلة ذات صلة

الأسئلة الشائعة

هل استخدام مزود طرف ثالث مع Claude Code يخالف شروط Anthropic؟

لا. نمط ANTHROPIC_BASE_URL مدعوم لتوجيه الطلبات عبر Bedrock وVertex AI وFoundry والبوابات المخصصة. ما تم حظره هو أدوات كانت تزيف معرف عميل Claude Code للوصول إلى تسعير اشتراكات Anthropic.

هل تعمل حلقة وكيل Claude Code مع DeepSeek V4 Pro؟

تعمل الحلقة الأساسية مثل تحرير الملفات، أوامر الشل، والمهام متعددة الخطوات. القيود الرئيسية عبر مزودي الطرف الثالث هي أدوات MCP ومدخلات الصور/الرؤية.

لماذا تظهر عبارة `enterprise config` وأنا لست ضمن خطة مؤسسة؟

هذه تسمية داخلية في Claude Code لأي تهيئة مزود خارجي. لا تعني أنك تحتاج خطة Enterprise.

هل يمكنني التبديل بين Anthropic ومزود طرف ثالث داخل نفس الجلسة؟

لا. تتم قراءة ANTHROPIC_BASE_URL عند بدء التشغيل. للتبديل، أغلق Claude Code، عدّل البيئة أو الإعدادات، ثم ابدأ جلسة جديدة.

أداة DeepClaude تغلف هذا عبر خيارات مثل:

--backend ds
--backend anthropic

بوابتي خلف proxy. ماذا أفعل؟

اضبط:

export HTTPS_PROXY="http://your-proxy:8080"
export ANTHROPIC_BASE_URL="https://your-internal-gateway"

إذا كان proxy يعترض TLS، أضف شهادة CA:

export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"

اختبار `curl` يعمل لكن Claude Code يفشل. لماذا؟

Claude Code يرسل طلب تحقق إضافيًا قد يتضمن رؤوسًا أو تنسيقًا مختلفًا. استخدم:

claude --debug

وقارن الطلب الفعلي مع اختبار curl.

الخلاصة

Invalid custom3p enterprise config هو خطأ تحقق من التهيئة. عالجه بهذا الترتيب:

احذف /v1 من ANTHROPIC_BASE_URL.
استخدم ANTHROPIC_AUTH_TOKEN أو ANTHROPIC_API_KEY حسب نوع المصادقة.
تحقق من صحة ~/.claude/settings.json.
أكمل onboarding في ~/.claude.json.
تأكد أن البوابة تمرر رؤوس Claude Code.
راجع سياسات المؤسسة إن وجدت.

بعد ضبط هذه النقاط، يمكن تشغيل Claude Code عبر OpenRouter أو LiteLLM أو vLLM مع نموذج مثل DeepSeek V4 Pro، مع الانتباه إلى القيود المتعلقة بـ MCP والرؤية.

الحصول على Gemini API مجاني وغير محدود

Yusuf Khalidd — Sat, 09 May 2026 07:02:50 +0000

توفّر عائلة Gemini من Google نماذج قوية لتطبيقات الذكاء الاصطناعي، لكن التكلفة قد تتزايد بسرعة عندما يبدأ آلاف المستخدمين في استدعاء نقطة النهاية الخاصة بك. يغيّر Puter.js هذا النمط: يمكنك استدعاء نماذج Gemini وGemma من المتصفح بدون مفتاح Google API، وبدون مشروع Google Cloud، وبدون خادم وسيط. يتحمّل المستخدم النهائي الاستخدام عبر حساب Puter الخاص به، بينما تبقى واجهة المطوّر مجانية وغير محدودة.

جرّب Apidog اليوم

الخلاصة

Puter.js يمنحك وصولًا مجانيًا وغير محدود من جهة المطوّر إلى كتالوج Gemini وGemma بدون مفتاح Google API.
النماذج المدعومة تشمل: 2.5 Pro و2.5 Flash و2.5 Flash Lite و2.0 Flash و2.0 Flash Lite و3 Flash Preview.
عائلة Gemma المدعومة تشمل: Gemma 2 وGemma 3 وGemma 4 بأحجام متعددة.
تحتاج إلى وسم <script> واحد واستدعاء دالة واحدة لتشغيل Gemini داخل المتصفح.
يدعم Puter.js البث المباشر، إدخال الصور، المحادثات متعددة الأدوار، وضبط درجة الحرارة.
استخدم Apidog لمقارنة التكاملات وتخطيط الانتقال إلى واجهة Gemini الرسمية عند الحاجة.

كيف يعمل نموذج "مجاني وغير محدود"

بدلًا من أن تحتفظ أنت بمفتاح Google AI Studio وتدفع تكلفة كل رمز مميز، يسجّل المستخدم الدخول إلى Puter، ثم تُخصم تكلفة الاستدعاء من حسابه. يحصل المستخدمون الجدد على رصيد بداية، ويمكنهم إعادة الشحن إذا احتاجوا إلى استخدام إضافي.

بالنسبة لك كمطوّر:

لا تحتاج إلى مشروع Google Cloud.
لا تحتاج إلى إدارة مفاتيح API أو متغيرات بيئة.
لا توجد علاقة فوترة مباشرة مع Google.
لا تحتاج إلى خادم وسيط فقط لإخفاء المفتاح.
يتوسع الاستخدام مع عدد المستخدمين بدلًا من أن يتراكم كله على حسابك.

المفاضلة المهمة: Puter.js موجّه أولًا للمتصفح. إذا كنت تحتاج إلى مهام خلفية مثل cron jobs أو webhooks أو معالجة دفعية بدون جلسة مستخدم، فاستخدم واجهة Gemini الرسمية.

الخطوة 1: تثبيت Puter.js

لصفحة HTML بسيطة، أضف سكريبت CDN:

<script src="https://js.puter.com/v2/"></script>

هذا يكفي لتشغيل Puter.js في المتصفح.

إذا كنت تستخدم تطبيقًا مبنيًا بأداة تجميع مثل Vite أو Next.js أو Webpack:

npm install @heyputer/puter.js

ثم استورده في الكود:

import { puter } from '@heyputer/puter.js';

الخطوة 2: اختيار نموذج Gemini أو Gemma

اختر النموذج بناءً على نوع المهمة:

معرف النموذج	متى تستخدمه
`google/gemini-2.5-pro`	للاستدلال العميق، التحليل المعقد، ومهام السياق الطويل
`google/gemini-2.5-flash`	الخيار الافتراضي لمعظم تطبيقات الدردشة والأسئلة والأجوبة
`google/gemini-2.5-flash-lite`	مهام التصنيف والوسم عالية الحجم حيث تكون السرعة مهمة
`google/gemini-2.0-flash`	خيار مستقر لسلوك معروف ومتوقع
`google/gemini-3-flash-preview`	تجربة أحدث إصدار معاينة من Flash
`google/gemma-3-27b-it`	نموذج Gemma مفتوح ومضبوط للتعليمات
`google/gemma-4-31b-it`	نموذج Gemma أكبر عندما تحتاج إلى جودة أعلى ضمن عائلة Gemma

للبداية، استخدم:

google/gemini-2.5-flash

ثم انتقل إلى google/gemini-2.5-pro فقط عندما تحتاج إلى تفكير أعمق أو تحليل أكثر تعقيدًا.

الخطوة 3: أول استدعاء إلى Gemini من المتصفح

هذا مثال كامل قابل للتشغيل:

<!DOCTYPE html>
<html lang="ar">
<body>
  <div id="output"></div>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    const output = document.getElementById('output');

    puter.ai.chat(
      "اشرح تعلم الآلة في ثلاث جمل",
      { model: 'google/gemini-2.5-flash' }
    ).then(response => {
      output.textContent = response;
    }).catch(error => {
      console.error(error);
      output.textContent = 'حدث خطأ أثناء استدعاء النموذج.';
    });
  </script>
</body>
</html>

افتح الملف في المتصفح. عند أول استخدام، يتعامل Puter مع تسجيل دخول المستخدم أو إنشاء حساب. لا تحتاج إلى مفتاح API أو خادم خلفي.

الخطوة 4: بث الاستجابة في واجهة الدردشة

في واجهات الدردشة، لا تنتظر اكتمال النص بالكامل. استخدم stream: true لعرض الاستجابة تدريجيًا:

const outputDiv = document.getElementById('output');

const response = await puter.ai.chat(
  "اشرح عملية البناء الضوئي بالتفصيل",
  {
    model: 'google/gemini-2.5-flash',
    stream: true,
  }
);

for await (const part of response) {
  if (part?.text) {
    outputDiv.innerHTML += part.text;
  }
}

كل part.text يمثل جزءًا من الاستجابة. أضفه مباشرة إلى واجهة المستخدم للحصول على تجربة شبيهة بتطبيقات الدردشة الحديثة.

الخطوة 5: استخدام Gemini مع الصور

يدعم Gemini الإدخال متعدد الوسائط. مرّر رابط الصورة كوسيط ثانٍ:

puter.ai.chat(
  "ماذا ترى في هذه الصورة؟ صف الألوان والعناصر والمزاج العام.",
  "https://assets.puter.site/doge.jpeg",
  { model: 'google/gemini-2.5-flash' }
).then(response => {
  puter.print(response);
});

أمثلة عملية:

توليد النص البديل للصور.
تحليل لقطات الشاشة.
استخراج معلومات من صور المنتجات.
مراجعة واجهات المستخدم بصريًا.
دعم أدوات الوصول.
التعرف الضوئي على الحروف OCR في بعض الحالات.

جودة رؤية Gemini قوية في الصور الطبيعية والرسوم البيانية، لكن لقطات الشاشة النصية الكثيفة قد تحتاج إلى اختبار ومقارنة حسب حالتك.

الخطوة 6: ضبط درجة الحرارة

استخدم temperature للتحكم في عشوائية المخرجات:

const response = await puter.ai.chat(
  'اكتب قصة قصيرة إبداعية عن روبوت يعمل طاهيًا',
  {
    model: 'google/gemini-2.5-flash',
    temperature: 0.8,
  }
);

console.log(response);

قاعدة عملية:

0.0 إلى 0.3: مخرجات أكثر ثباتًا، مناسبة للتصنيف والبيانات المنظمة.
0.4 إلى 0.7: توازن مناسب للدردشة العامة.
0.8 إلى 1.0: مخرجات أكثر تنوعًا، مناسبة للكتابة الإبداعية.

مثال لمهمة تصنيف:

const response = await puter.ai.chat(
  'صنّف هذه الرسالة كـ: دعم، مبيعات، أو شكوى. الرسالة: لا أستطيع تسجيل الدخول.',
  {
    model: 'google/gemini-2.5-flash-lite',
    temperature: 0.1,
  }
);

الخطوة 7: بناء محادثة متعددة الأدوار

مرّر مصفوفة رسائل بدلًا من نص واحد:

const messages = [
  { role: 'user', content: 'أنا أبني تطبيق Next.js مع PostgreSQL.' },
  { role: 'assistant', content: 'فهمت. ما الجزء الذي تحتاج مساعدة فيه؟' },
  { role: 'user', content: 'كيف أنظم ملفات migrations؟' },
];

const response = await puter.ai.chat(messages, {
  model: 'google/gemini-2.5-pro',
});

console.log(response);

للاستخدام داخل تطبيق دردشة، احتفظ بالحالة محليًا:

const messages = [];

async function sendMessage(userText) {
  messages.push({ role: 'user', content: userText });

  const assistantReply = await puter.ai.chat(messages, {
    model: 'google/gemini-2.5-flash',
  });

  messages.push({ role: 'assistant', content: assistantReply });

  return assistantReply;
}

بهذا الشكل يحصل النموذج على سياق المحادثة بالكامل في كل استدعاء.

مقارنة Gemini بنماذج أخرى على نفس المطالبة

يعرض Puter عدة نماذج عبر واجهة واحدة. يمكنك اختبار نفس المطالبة على أكثر من نموذج:

const models = [
  'google/gemini-2.5-flash',
  'claude-sonnet-4-6',
  'gpt-5.5',
  'x-ai/grok-4.3',
];

const prompt = "Refactor this React component to use hooks: ...";

for (const model of models) {
  const start = performance.now();

  const response = await puter.ai.chat(prompt, { model });

  const elapsed = performance.now() - start;

  console.log(`${model}: ${elapsed.toFixed(0)}ms`);
  console.log(response);
  console.log('---');
}

استخدم هذا النمط لتقييم:

زمن الاستجابة.
جودة الإجابة.
الاتساق بين المحاولات.
ملاءمة النموذج للمهمة.

لا تعتمد على تجربة واحدة فقط. اختبر مجموعة مطالبات تمثل استخدامك الحقيقي.

ماذا يدعم Puter.js مع Gemini

تحصل عادةً على:

نماذج Gemini 2.5 و2.0 و3 Flash Preview و2.5 Pro.
نماذج Gemma المفتوحة.
المحادثات متعددة الأدوار.
الاستجابات المتدفقة.
إدخال الصور عبر عنوان URL.
إعدادات مثل temperature وmax_tokens ومطالبات النظام حسب الدعم المتاح.

وقد لا تحصل على كل ميزات Gemini الرسمية، حسب إصدار Puter والدعم الحالي، مثل:

استدعاء الدوال الأصلي.
أدوات تنفيذ الأكواد.
ترسيخ بحث Google.
الوصول الكامل إلى نافذة سياق Gemini القصوى.
تشغيل خلفي بدون جلسة مستخدم.
رؤية مباشرة لحدود معدل Google.

إذا كنت تبني وكيلًا معقدًا يحتاج إلى أدوات تنفيذ، ترسيخ بحث، أو تحكم كامل في البنية الخلفية، فواجهة Google AI Studio الرسمية قد تكون أنسب. أما لتطبيقات الدردشة، الأسئلة والأجوبة، توليد المحتوى، والنماذج الأولية داخل المتصفح، فـ Puter.js يكفي غالبًا.

متى تستخدم Puter بدل واجهة Gemini الرسمية

استخدم Puter عندما:

تبني تطبيقًا عامًا مجانيًا وتريد تجنب مخاطر الفوترة.
تعمل على نموذج أولي أو مشروع هاكاثون.
تريد تشغيل Gemini داخل موقع ثابت.
لا تريد إعداد Google Cloud.
يمكن للمستخدمين تسجيل الدخول إلى Puter.

استخدم واجهة Gemini الرسمية عندما:

تحتاج إلى استدعاءات من الخادم.
لديك مهام مجدولة أو معالجة دفعية.
تحتاج إلى webhooks أو تكاملات خلفية.
تحتاج إلى تنفيذ أكواد أو ترسيخ بحث.
تحتاج إلى متطلبات امتثال أو علاقة مباشرة مع Google.
لا تريد إضافة خطوة تسجيل دخول Puter للمستخدمين.

لشرح أوسع حول Gemini 3 Flash، راجع: كيفية استخدام واجهة برمجة تطبيقات Gemini 3 Flash Preview.

اختبار التكامل باستخدام Apidog

استدعاءات Puter تحدث داخل المتصفح، لذلك لا تختبرها بنفس طريقة اختبار REST API خلفية. النمط العملي هو:

أنشئ صفحة HTML صغيرة تحتوي على Puter.js.
اجعل المطالبة قابلة للتمرير عبر query parameter.
استخدم الصفحة لاختبار تجربة المستخدم والتدفق داخل المتصفح.
استخدم Apidog لاختبار واجهة Gemini الرسمية إذا قررت الانتقال إلى الخادم.
احتفظ ببيئتين منفصلتين: واحدة للنموذج الأولي عبر Puter، وأخرى للإنتاج عبر Gemini API.

مثال صفحة اختبار بسيطة:

<!DOCTYPE html>
<html lang="ar">
<body>
  <pre id="output">جارٍ التحميل...</pre>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    const params = new URLSearchParams(location.search);
    const prompt = params.get('prompt') || 'اكتب ملخصًا قصيرًا عن REST APIs';

    puter.ai.chat(prompt, {
      model: 'google/gemini-2.5-flash',
    }).then(response => {
      document.getElementById('output').textContent = response;
    }).catch(error => {
      document.getElementById('output').textContent = error.message;
    });
  </script>
</body>
</html>

ثم شغّلها مثلًا:

http://localhost:5173/?prompt=اشرح%20JSON%20Schema

قم بـ تنزيل Apidog وأنشئ بيئتين:

puter-prototype: عنوان الصفحة المحلية التي تستضيف Puter.js.
gemini-prod: https://generativelanguage.googleapis.com/v1.

لأنماط اختبار API الأوسع، راجع: أداة اختبار API لمهندسي ضمان الجودة.

مسارات LLM مجانية أخرى عبر Puter

نفس نموذج الدفع من جهة المستخدم ينطبق على مزودين آخرين عبر Puter. يمكنك تغيير قيمة model فقط لتجربة نماذج مختلفة.

روابط مفيدة:

مثال تبديل النموذج:

const response = await puter.ai.chat(
  "لخّص هذا النص في خمس نقاط: ...",
  {
    model: 'google/gemini-2.5-flash',
  }
);

غيّرها إلى نموذج آخر عند المقارنة:

const response = await puter.ai.chat(
  "لخّص هذا النص في خمس نقاط: ...",
  {
    model: 'claude-sonnet-4-6',
  }
);

الأسئلة الشائعة

هل الاستخدام غير محدود فعلًا؟

غير محدود من جهة المطوّر. المستخدم النهائي يستخدم رصيد حسابه على Puter، والحسابات الجديدة تحصل على رصيد بداية.

هل أحتاج إلى حساب Google أو مشروع Google Cloud؟

لا. Puter يتعامل مع الاستدعاء الأساسي، ولن تحتاج إلى مفتاح Google API داخل تطبيقك.

هل يمكن استخدامه في الإنتاج؟

نعم لتطبيقات الويب المعتمدة على المتصفح، بشرط أن تكون خطوة تسجيل دخول Puter مناسبة لتجربة المستخدم لديك.

هل يعمل Gemini عبر Puter مثل واجهة Gemini الرسمية؟

النموذج الأساسي هو Gemini، لكن طبقة الاستدعاء تمر عبر Puter. قد تختلف بعض الميزات أو الحدود حسب الدعم المتاح.

ماذا عن سياق Gemini الكبير جدًا؟

إذا كنت تحتاج إلى الوصول الكامل لسياق طويل جدًا، فاستخدم واجهة Google AI Studio الرسمية. معظم تطبيقات الدردشة والأسئلة والأجوبة لا تحتاج إلى هذا الحد.

هل يمكن استخدامه في بوت Discord أو خدمة خلفية؟

ليس بسلاسة. Puter.js يفترض وجود متصفح وجلسة مستخدم. للخدمات الخلفية، استخدم Gemini API الرسمية.

ما النموذج الافتراضي المقترح؟

ابدأ بـ google/gemini-2.5-flash. استخدم google/gemini-2.5-pro للمهام الأصعب، وgoogle/gemini-2.5-flash-lite للتصنيف عالي الحجم.

هل يدعم Puter توليد الصور عبر Imagen؟

حسب المحتوى الأصلي، Puter يعرض توليد الصور عبر gpt-image-2 ومتغيرات DALL-E من OpenAI، وليس Imagen. راجع احصل على واجهة برمجة تطبيقات GPT-5.5 مجانية وغير محدودة لمسار توليد الصور.

خاتمة

إذا كنت تريد تشغيل Gemini داخل تطبيق ويب بدون مفاتيح API أو Google Cloud أو خادم وسيط، فإن Puter.js هو أسرع مسار عملي. أضف السكريبت، اختر google/gemini-2.5-flash، ثم ابدأ بإرسال المطالبات من المتصفح.

استخدم واجهة Gemini الرسمية عندما تحتاج إلى تشغيل خلفي، ضبط دقيق، أدوات تنفيذ أكواد، أو تحكم كامل في السياق والامتثال. أما للنماذج الأولية، تطبيقات الهاكاثون، المواقع الثابتة، وتطبيقات الدردشة العامة، فـ Puter.js يقلل وقت الإعداد بشكل كبير.

قم ببناء الطلبات ومقارنتها في Apidog، ثم اختر المسار الأنسب بين Puter والنشر الرسمي عبر Gemini API.

الحصول على API GPT-5.5 مجاني وغير محدود وجميع نماذج OpenAI

Yusuf Khalidd — Sat, 09 May 2026 02:39:38 +0000

يأتي GPT-5.5 من OpenAI مع واجهة برمجة تطبيقات مدفوعة: 5 دولارات لكل مليون رمز إدخال، و30 دولارًا لكل مليون رمز إخراج. إذا كنت تبني مشروعًا جانبيًا، نموذجًا أوليًا لهاكاثون، أو تطبيقًا عامًا مجانيًا، فقد تصبح الفاتورة عائقًا قبل الإطلاق. الحل العملي هنا هو Puter.js: مكتبة تعمل من المتصفح وتتيح الوصول إلى كتالوج OpenAI مثل GPT-5.5 وGPT-5.5 Pro ونماذج GPT-5.x وGPT-Image-2 وDALL-E وOpenAI TTS بدون مفتاح OpenAI، مع تحميل تكلفة الاستخدام على المستخدم النهائي عبر حساب Puter.

جرّب Apidog اليوم

ملخص سريع

Puter.js يمنح المطورين وصولًا إلى نماذج OpenAI من المتصفح بدون مفتاح API أو خادم.
النماذج النصية تشمل: gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5, gpt-5-mini, o1, o3, gpt-4.1, gpt-4o، ومتغيرات الدردشة والكودكس.
الصور: gpt-image-2, gpt-image-1.5, dall-e-3.
تحويل النص إلى كلام: gpt-4o-mini-tts, tts-1, tts-1-hd.
التثبيت يمكن أن يكون عبر وسم <script> واحد.
الميزات المدعومة تشمل البث، الرؤية، استدعاء الدوال، توليد الصور، وتحويل النص إلى كلام.
يدفع المستخدم النهائي من حساب Puter الخاص به، وليس حساب المطور.
استخدم Apidog لمقارنة نفس الـ prompt بين Puter وواجهة OpenAI API الرسمية عند التخطيط للترحيل.

كيف يعمل نموذج “مجاني غير محدود”

Puter.js يغيّر طريقة الفوترة. بدلًا من أن تضع مفتاح OpenAI داخل مشروعك وتدفع تكلفة كل طلب، يسجل المستخدم الدخول إلى Puter، وتُخصم تكلفة الطلب من رصيده هو.

هذا يعني عمليًا:

لا تحتاج إلى حساب OpenAI داخل المشروع.
لا يوجد مفتاح API داخل الواجهة الأمامية أو المستودع.
لا تتحمل أنت فاتورة الاستخدام.
كل مستخدم يعمل من خلال حساب Puter الخاص به.

المقايضة المهمة: Puter مناسب أساسًا لتطبيقات المتصفح. إذا كنت تحتاج إلى تنفيذ الطلبات من خادم Node.js، أو jobs، أو webhooks، فواجهة OpenAI API الرسمية تبقى الخيار الصحيح.

الخطوة 1: التثبيت

أبسط طريقة هي استخدام CDN:

<script src="https://js.puter.com/v2/"></script>

مثال HTML كامل:

<!DOCTYPE html>
<html lang="ar">
<body>
  <script src="https://js.puter.com/v2/"></script>
</body>
</html>

إذا كنت تستخدم bundler في تطبيق حديث:

npm install @heyputer/puter.js

ثم:

import { puter } from '@heyputer/puter.js';

استخدم CDN للنماذج الأولية والمواقع الثابتة وإضافات المتصفح. استخدم نسخة NPM إذا كنت تريد تكاملًا أفضل مع TypeScript وبيئة build.

الخطوة 2: اختر النموذج المناسب

Puter يعرض نماذج GPT-5.x إلى جانب النماذج الأقدم. استخدم هذا الجدول كبداية:

معرف النموذج	متى تستخدمه
`gpt-5.5-pro`	الاستدلال العميق، وكلاء البرمجة، التحليل المعقد
`gpt-5.5`	النموذج الافتراضي لمعظم مهام الدردشة والاستدلال اليومي
`gpt-5.4-nano`	مهام التصنيف السريعة والرخيصة بكميات كبيرة
`gpt-5.4-mini`	واجهات الدردشة التي تحتاج توازنًا بين السرعة والجودة
`gpt-5.3-codex`	مهام البرمجة والكود
`o3`	سلاسل الاستدلال الطويلة والمعقدة
`o1-pro`	التخطيط متعدد الخطوات
`gpt-4.1`, `gpt-4o`, `gpt-4o-mini`	خط أساس مستقر ومفهوم جيدًا

لنماذج الصور:

gpt-image-2: الأحدث لتوليد الصور.
gpt-image-1.5, gpt-image-1, dall-e-3, dall-e-2: خيارات أقدم ومستقرة.

لنماذج تحويل النص إلى كلام:

gpt-4o-mini-tts: خيار حديث وطبيعي.
tts-1, tts-1-hd: خيارات TTS كلاسيكية بزمن استجابة أقل.

الخطوة 3: نفّذ أول طلب إلى GPT-5.5

هذا هو الحد الأدنى لاستدعاء الدردشة:

<!DOCTYPE html>
<html>
<body>
  <script src="https://js.puter.com/v2/"></script>

  <script>
    puter.ai.chat(
      "Explain WebSockets in three sentences",
      { model: "gpt-5.5" }
    ).then(response => {
      puter.print(response);
    });
  </script>
</body>
</html>

افتح الملف في المتصفح. سيعالج Puter الطلب، ويطلب من المستخدم تسجيل الدخول أو إنشاء حساب Puter عند الحاجة، ثم يطبع الرد في الصفحة.

لا يوجد:

مفتاح API
متغيرات بيئة
خادم وسيط
إعداد فوترة من جانبك

الخطوة 4: بث الاستجابة Streaming

لواجهات الدردشة، استخدم stream: true حتى يرى المستخدم الرد أثناء توليده:

const response = await puter.ai.chat(
  "Explain the theory of relativity in detail",
  {
    model: "gpt-5.5",
    stream: true
  }
);

for await (const part of response) {
  puter.print(part?.text);
}

في تطبيق حقيقي، بدلًا من puter.print، أضف part.text إلى عنصر الرسالة داخل واجهة المستخدم:

const messageEl = document.querySelector("#assistant-message");

for await (const part of response) {
  messageEl.textContent += part?.text || "";
}

الخطوة 5: إدخال الصور Vision

يمكنك تمرير رابط صورة كوسيط ثانٍ، ثم طرح سؤال متعلق بها:

puter.ai.chat(
  "What do you see in this image? Describe colors, objects, and mood.",
  "https://assets.puter.site/doge.jpeg",
  { model: "gpt-5.5" }
).then(response => {
  puter.print(response);
});

حالات الاستخدام العملية:

توليد alt text
تحليل لقطات الشاشة
OCR مبسط
أسئلة وأجوبة حول الصور
أدوات وصول لذوي الاحتياجات الخاصة

الخطوة 6: توليد الصور

توليد الصور يتم عبر txt2img. الدالة تعيد عنصر <img> جاهزًا للإضافة إلى الصفحة:

puter.ai.txt2img(
  "A futuristic cityscape at night, cinematic, neon, rain",
  { model: "gpt-image-2" }
).then(imageElement => {
  document.body.appendChild(imageElement);
});

مثال أكثر عملية مع زر:

<input id="prompt" placeholder="اكتب وصف الصورة" />
<button id="generate">توليد</button>
<div id="result"></div>

<script>
  document.querySelector("#generate").addEventListener("click", async () => {
    const prompt = document.querySelector("#prompt").value;

    const image = await puter.ai.txt2img(prompt, {
      model: "gpt-image-2"
    });

    const result = document.querySelector("#result");
    result.innerHTML = "";
    result.appendChild(image);
  });
</script>

يدفع المستخدم تكلفة توليد الصورة من رصيده في Puter، وليس من حسابك.

الخطوة 7: تحويل النص إلى كلام TTS

استخدم txt2speech لتوليد ملف صوتي من النص:

puter.ai.txt2speech(
  "Welcome back. Your account balance is $1,247.50.",
  {
    provider: "openai",
    model: "gpt-4o-mini-tts"
  }
).then(audio => {
  audio.setAttribute("controls", "");
  document.body.appendChild(audio);
});

استخدمه في:

المساعدات الصوتية
قراءة التنبيهات
مقدمات البودكاست
السرد داخل التطبيقات
ميزات الوصول accessibility

الخطوة 8: استدعاء الدوال Function Calling

يدعم Puter شكل OpenAI القياسي لتعريف الأدوات. تعرّف الدوال، يطلب النموذج استدعاء أداة، ثم تنفذها أنت في التطبيق.

const tools = [{
  type: "function",
  function: {
    name: "get_weather",
    description: "Get the current weather for a city.",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string" }
      },
      required: ["city"]
    }
  }
}];

const response = await puter.ai.chat(
  "What's the weather in Tokyo right now?",
  {
    model: "gpt-5.5",
    tools
  }
);

const toolCalls = response.message.tool_calls;

if (toolCalls?.length) {
  const call = toolCalls[0];

  console.log(call.function.name);
  console.log(call.function.arguments);

  // نفّذ الدالة من جانبك، ثم أرسل النتيجة للنموذج إذا احتجت إلى رد نهائي.
}

هذا مفيد إذا كنت تريد ربط النموذج بعمليات مثل:

البحث داخل قاعدة بيانات
استدعاء API داخلي
جلب حالة طلب
حساب سعر
التحقق من توفر منتج

شكل استدعاء الدوال قريب من OpenAI، لذلك يمكن نقل تعريفات الأدوات الحالية بسهولة. لاختبار تدفقات تعتمد على الأدوات في إعدادات بجودة إنتاجية، راجع اختبار خادم MCP في Apidog.

الخطوة 9: ضبط temperature و max_tokens

مرر إعدادات OpenAI الشائعة داخل كائن الخيارات:

const response = await puter.ai.chat(
  "Tell me about Mars",
  {
    model: "gpt-5.5",
    temperature: 0.2,
    max_tokens: 200
  }
);

إرشادات سريعة:

استخدم temperature: 0.0 إلى 0.3 للإجابات الواقعية والمتسقة.
استخدم temperature: 0.7 إلى 1.0 للكتابة الإبداعية.
استخدم max_tokens لتحديد طول الرد وتقليل الهدر.
في تطبيق عام، اجعل max_tokens محدودًا حتى لا يستهلك المستخدم رصيده بسرعة.

ما الذي تحصل عليه وما الذي لا تحصل عليه

الوصول إلى GPT-5.5 عبر Puter مفيد، لكنه ليس نسخة كاملة من كل سطح OpenAI API الرسمي.

ما تحصل عليه

نماذج GPT-5.x بما في ذلك gpt-5.5 وgpt-5.5-pro.
نماذج OpenAI الأقدم مثل gpt-4.1, gpt-4o, o1, o3.
توليد الصور عبر GPT-Image وDALL-E.
تحويل النص إلى كلام عبر نماذج OpenAI TTS.
البث Streaming.
الرؤية Vision.
استدعاء الدوال Function Calling.
التحكم في temperature وmax_tokens.
تشغيل مباشر من المتصفح بدون خادم.

ما قد لا تحصل عليه

Responses API الرسمية.
التخزين المؤقت للموجهات Prompt Caching.
Files API.
تشغيل مريح من الخادم بدون جلسة مستخدم.
رؤوس حدود المعدل المباشرة من OpenAI.
وضع الإخراج المنظم الكامل وفرض JSON Schema كما في OpenAI الرسمية.

إذا كان تطبيقك يعتمد على المتصفح، فـ Puter خيار سريع. إذا كنت تبني بنية خلفية أو نظامًا إنتاجيًا عميقًا، فاستخدم OpenAI API الرسمية.

متى تستخدم Puter ومتى تستخدم OpenAI API الرسمية

استخدم Puter عندما:

تبني تطبيقًا عامًا مجانيًا ولا تريد تحمل الفاتورة.
تعمل على نموذج أولي سريع.
تشارك في هاكاثون.
تنشر موقعًا ثابتًا أو إضافة متصفح.
لا تريد إعداد خادم وسيط.
يمكن للمستخدمين تسجيل الدخول إلى Puter.

استخدم OpenAI API الرسمية عندما:

تحتاج إلى تشغيل الطلبات من الخادم.
لديك jobs أو cron tasks أو webhooks.
تحتاج إلى batch processing.
تحتاج إلى Prompt Caching.
تحتاج إلى Responses API أو Files API.
تحتاج إلى مخرجات منظمة صارمة.
لديك متطلبات امتثال أو عقود مؤسسية.
لا تريد فرض تسجيل دخول Puter على المستخدم.

كثير من المشاريع تبدأ بـ Puter للنمذجة السريعة، ثم تنتقل إلى OpenAI API الرسمية عند الوصول إلى حدود المتصفح أو متطلبات الإنتاج.

لإعداد إنتاجي مدفوع، راجع كيفية استخدام GPT-5.5 API.

اختبار الدمج في Apidog

مكالمات Puter تحدث داخل المتصفح، لذلك لا تختبرها مثل REST API خلفية مباشرة. النمط العملي هو:

أنشئ صفحة HTML صغيرة تستخدم Puter.
اجعل الـ prompt يأتي من query parameter.
استخدم Apidog لاختبار OpenAI API الرسمية عند التخطيط للترحيل.
احتفظ ببيئتين منفصلتين: واحدة للنموذج الأولي وواحدة للإنتاج.

مثال صفحة اختبار بسيطة:

<!DOCTYPE html>
<html>
<body>
  <pre id="output"></pre>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    const params = new URLSearchParams(location.search);
    const prompt = params.get("prompt") || "Say hello";

    puter.ai.chat(prompt, {
      model: "gpt-5.5"
    }).then(response => {
      document.querySelector("#output").textContent = response;
    });
  </script>
</body>
</html>

بعد ذلك يمكنك تشغيلها هكذا:

http://localhost:5173/?prompt=Explain%20JWT%20in%203%20points

قم بتنزيل Apidog وأنشئ بيئتين:

puter-prototype: عنوان محلي يستضيف صفحة Puter.
openai-prod: مثل https://api.openai.com/v1.

بهذا تستطيع مقارنة السلوك، ثم الترحيل عندما يصبح المشروع جاهزًا. لأنماط اختبار API الأوسع، راجع أداة اختبار API لمهندسي ضمان الجودة.

الأسئلة الشائعة

هل هذا غير محدود فعلًا؟

غير محدود من جانب المطور. المستخدم النهائي يستخدم رصيد حسابه في Puter. الحسابات الجديدة تحصل على رصيد بدء، ويمكن للمستخدم إعادة الشحن عند الحاجة.

هل أحتاج إلى حساب OpenAI؟

لا. Puter يدير الاتصال بواجهة OpenAI API. أنت لا ترى مفتاح OpenAI ولا تخزنه.

هل يمكن استخدامه في الإنتاج؟

نعم، لتطبيقات المتصفح. السؤال العملي هو: هل يقبل المستخدمون تسجيل الدخول إلى Puter؟ إذا كانت الإجابة نعم، يمكنك نشره.

هل أداء GPT-5.5 عبر Puter هو نفسه API الرسمية؟

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

ماذا عن Prompt Caching؟

لا يعرض Puter ضوابط Prompt Caching مثل OpenAI الرسمية. إذا كان لديك system prompt كبير وثابت وتحتاج إلى خصومات التخزين المؤقت، فاستخدم OpenAI API الرسمية.

هل يمكن استخدام Puter من خدمة خلفية؟

ليس بسلاسة. Puter مصمم أساسًا للمتصفح ويفترض وجود جلسة مستخدم. للخدمات الخلفية، استخدم OpenAI API الرسمية. لخيارات مجانية من جانب الخادم، راجع كيفية استخدام GPT-5.5 API مجانًا.

ما النموذج الافتراضي المناسب؟

استخدم gpt-5.5 لمعظم مهام الدردشة والاستدلال.
استخدم gpt-5.4-nano للتصنيف السريع بكميات كبيرة.
استخدم gpt-5.5-pro للمهام الصعبة.
استخدم o3 لسلاسل الاستدلال الطويلة.

هل يمكن أن تكون التكلفة عالية على المستخدمين؟

معظم استخدامات الدردشة تستهلك تكلفة صغيرة لكل جلسة. توليد الصور أغلى عادة، لذلك حدّد max_tokens للنصوص، وتجنب الطلبات غير الضرورية، وأظهر للمستخدم ما الذي سيحدث قبل تنفيذ عمليات مكلفة.

هل يمكن توليد الصور باستخدام Puter؟

نعم، عبر txt2img باستخدام gpt-image-2 أو DALL-E. يدفع المستخدم من رصيده في Puter. للدليل الرسمي لواجهة API المدفوعة، راجع كيفية استخدام GPT-Image-2 API.

خلاصة القول

Puter.js يمنحك طريقة سريعة لبناء تطبيقات متصفح تستخدم نماذج OpenAI بدون مفتاح API وبدون خادم وبدون تحمل فاتورة الاستخدام. أضف السكربت، اختر النموذج، ثم نفّذ puter.ai.chat.

إذا كنت تبني:

نموذجًا أوليًا
مشروع هاكاثون
أداة عامة مجانية
موقعًا ثابتًا
إضافة متصفح

فـ Puter خيار عملي للبدء بسرعة.

أما إذا كنت تحتاج إلى تشغيل من الخادم، أو Prompt Caching، أو Responses API، أو مخرجات منظمة صارمة، فواجهة OpenAI API الرسمية هي المسار الأنسب.

أنشئ الطلب مرة واحدة في Apidog، وقارن Puter مقابل واجهة API الرسمية، ثم اختر المسار الذي يناسب بنية تطبيقك.

الحصول على API مجاني وغير محدود لـ Claude Opus 4.7

Yusuf Khalidd — Sat, 09 May 2026 02:32:38 +0000

تُعد عائلة نماذج Claude من Anthropic خيارًا قويًا للبرمجة، الوكلاء (agentic workflows)، والاستدلال طويل السياق، لكن تكلفة API قد تجعل التجارب الجانبية مكلفة بسرعة. باستخدام Puter.js يمكنك استدعاء نماذج Claude مثل Opus 4.7 وSonnet 4.6 وHaiku 4.5 من المتصفح بدون مفتاح Anthropic، حيث يتحمل المستخدم النهائي الاستهلاك عبر حساب Puter بدلًا من المطور.

جرّب Apidog اليوم

هذا الدليل يوضح طريقة التنفيذ عمليًا: التثبيت، اختيار النموذج، أول استدعاء، البث، المحادثات متعددة الأدوار، وكيفية مقارنة Puter مع Anthropic API الرسمية قبل الانتقال للإنتاج.

خلاصة القول

Puter.js يتيح استدعاء Claude من المتصفح بدون مفتاح Anthropic API.
المستخدم النهائي يستخدم حساب Puter الخاص به، لذلك لا تتحمل أنت فاتورة Anthropic.
النماذج المدعومة تشمل: Opus 4.7, Opus 4.6, Opus 4.6 Fast, Opus 4.5, Opus 4.1, Opus 4, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Haiku 4.5.
تحتاج فقط إلى وسم <script> واستدعاء puter.ai.chat.
يدعم Puter المحادثات، المطالبات النظامية، والبث.
يمكنك استخدام Apidog لمقارنة نفس المطالبة بين Puter وAnthropic API الرسمية.

كيف يعمل النموذج بدون مفتاح API؟

Puter.js مكتبة تعمل من المتصفح. بدلًا من تخزين مفتاح Anthropic في تطبيقك أو خادمك، يسجّل المستخدم الدخول إلى Puter، ثم تُنفّذ الطلبات باستخدام حسابه.

هذا يعني عمليًا:

لا يوجد مفتاح API في الكود: لا أسرار، لا تدوير مفاتيح، ولا خطر تسريب.
لا توجد فاتورة Anthropic عليك: كل مستخدم يرتبط بحسابه الخاص.
لا تحتاج خادمًا وسيطًا: مناسب للمواقع الثابتة، النماذج الأولية، والهاكاثونات.

القيد الرئيسي: Puter مناسب أولًا لتطبيقات المتصفح. إذا كنت تحتاج بوت خلفي، وظيفة Cron، أو معالجة دفعية Server-side، فغالبًا ستحتاج Anthropic API الرسمية.

الخطوة 1: أضف Puter.js

في أبسط حالة، أضف السكريبت التالي إلى صفحة HTML:

<script src="https://js.puter.com/v2/"></script>

مثال صفحة كاملة:

<!DOCTYPE html>
<html lang="ar">
<body>
  <script src="https://js.puter.com/v2/"></script>
  <script>
    async function main() {
      const response = await puter.ai.chat(
        "اشرح مفهوم REST API باختصار",
        { model: "claude-sonnet-4-6" }
      );

      puter.print(response.message.content[0].text);
    }

    main();
  </script>
</body>
</html>

إذا كنت تستخدم Vite أو Webpack أو مشروعًا يعتمد على NPM:

npm install @heyputer/puter.js

import { puter } from "@heyputer/puter.js";

استخدم CDN للنماذج الأولية السريعة، واستخدم NPM عندما تحتاج دمجًا داخل تطبيق Frontend منظم.

الخطوة 2: اختر نموذج Claude المناسب

يعتمد اختيار النموذج على نوع المهمة. استخدم الجدول التالي كبداية:

معرف النموذج	متى تستخدمه؟
`claude-opus-4-7`	للاستدلال العميق، مراجعة الكود المعقدة، والمهام الوكالية متعددة الخطوات
`claude-opus-4-6`	مهام برمجية قوية مع جودة عالية
`claude-opus-4.6-fast`	عندما تحتاج Opus بزمن استجابة أقل
`claude-opus-4-5`	خيار مستقر للوكلاء وتطبيقات الإنتاج
`claude-opus-4-1`	نموذج أقدم بسلوك مستقر ومفهوم
`claude-opus-4`	الإصدار الأساسي من Opus 4
`claude-sonnet-4-6`	الخيار الافتراضي لمعظم التطبيقات اليومية
`claude-sonnet-4-5`	خيار جيد وأرخص نسبيًا لمعظم المهام
`claude-sonnet-4`	الإصدار الأساسي من Sonnet 4
`claude-haiku-4-5`	للتصنيف السريع والمهام كبيرة الحجم منخفضة التعقيد

قاعدة عملية:

استخدم claude-sonnet-4-6 كافتراضي.
استخدم claude-haiku-4-5 للتصنيف السريع أو الردود القصيرة.
استخدم claude-opus-4-7 عندما تكون جودة الاستدلال أهم من السرعة.

الخطوة 3: نفّذ أول استدعاء إلى Claude

أبسط استدعاء:

<!DOCTYPE html>
<html>
<body>
  <script src="https://js.puter.com/v2/"></script>
  <script>
    puter.ai.chat(
      "Explain quantum computing in simple terms",
      { model: "claude-sonnet-4-6" }
    ).then(response => {
      puter.print(response.message.content[0].text);
    });
  </script>
</body>
</html>

شكل الاستجابة يشبه Anthropic Messages API:

response.message.content[0].text

إذا كانت الاستجابة تحتوي على أكثر من جزء، يمكنك المرور على كل الكتل:

for (const block of response.message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

الخطوة 4: فعّل البث Streaming

لتحسين تجربة المستخدم في الردود الطويلة، استخدم stream: true:

const response = await puter.ai.chat(
  "اكتب شرحًا مفصلًا عن تأثير الذكاء الاصطناعي على تطوير البرمجيات",
  {
    model: "claude-sonnet-4-6",
    stream: true
  }
);

for await (const part of response) {
  puter.print(part?.text);
}

في واجهة دردشة، ألحق كل جزء بفقاعة الرسالة:

const output = document.querySelector("#output");

for await (const part of response) {
  if (part?.text) {
    output.textContent += part.text;
  }
}

الخطوة 5: استخدم محادثات متعددة الأدوار

بدلًا من إرسال نص واحد، أرسل مصفوفة رسائل:

const messages = [
  {
    role: "user",
    content: "أبني تطبيق Next.js يستخدم PostgreSQL."
  },
  {
    role: "assistant",
    content: "تمام. ما الجزء الذي تحتاج مساعدة فيه؟"
  },
  {
    role: "user",
    content: "كيف أنظم مجلد migrations؟"
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-opus-4-7"
});

console.log(response.message.content[0].text);

للحفاظ على سياق المحادثة، خزّن الرسائل في مصفوفة واحدة وأضف كل رسالة جديدة إليها:

const messages = [];

async function sendMessage(userText) {
  messages.push({ role: "user", content: userText });

  const response = await puter.ai.chat(messages, {
    model: "claude-sonnet-4-6"
  });

  const assistantText = response.message.content[0].text;

  messages.push({
    role: "assistant",
    content: assistantText
  });

  return assistantText;
}

الخطوة 6: أضف مطالبة نظامية

استخدم رسالة system لتحديد الدور، التنسيق، والقيود:

const messages = [
  {
    role: "system",
    content: "أنت مهندس Backend خبير. أجب بنقاط مرقمة ولا تتجاوز خمس نقاط."
  },
  {
    role: "user",
    content: "كيف أمنع SQL Injection في تطبيق Node.js؟"
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-sonnet-4-6"
});

console.log(response.message.content[0].text);

استخدم المطالبة النظامية لتحديد:

أسلوب الرد
اللغة
طول الإجابة
صيغة الإخراج مثل JSON أو Markdown
قواعد الأمان والسلوك

مثال لإخراج JSON:

const messages = [
  {
    role: "system",
    content: "أرجع الإجابة بصيغة JSON فقط بدون Markdown."
  },
  {
    role: "user",
    content: "استخرج اسم المنتج والسعر من النص: iPhone بسعر 999 دولار"
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-sonnet-4-6"
});

مقارنة النماذج على نفس المطالبة

لا تختَر النموذج بناءً على الاسم فقط. اختبر نفس المطالبة عبر أكثر من نموذج وقارن الزمن والجودة:

const models = [
  "claude-haiku-4-5",
  "claude-sonnet-4-6",
  "claude-opus-4-7"
];

const prompt = "Refactor this React component to use hooks: ...";

for (const model of models) {
  const start = performance.now();

  const response = await puter.ai.chat(prompt, { model });

  const elapsed = performance.now() - start;

  console.log(`${model}: ${elapsed.toFixed(0)}ms`);
  console.log(response.message.content[0].text);
  console.log("---");
}

النتيجة المتوقعة غالبًا:

Haiku أسرع للمهام البسيطة.
Sonnet أفضل توازن لمعظم تطبيقات الإنتاج.
Opus أفضل للمهام الصعبة والمعقدة.

لمقارنة Puter مع Anthropic API الرسمية داخل نفس سير الاختبار، يمكنك إعداد بيئتين في Apidog والتبديل بينهما عند الحاجة.

ما الذي تحصل عليه عبر Puter؟

تحصل على:

وصول إلى نماذج Claude المتاحة عبر Puter.
محادثات متعددة الأدوار.
مطالبات نظامية.
بث الاستجابات.
تشغيل من المتصفح بدون خادم وسيط.
عدم تخزين مفتاح Anthropic في تطبيقك.

وقد لا تحصل على، حسب دعم Puter الحالي:

نفس تحكم Anthropic الرسمي الكامل في الأدوات Function Calling / Tool Use.
دعم الرؤية أو مرفقات الصور.
تخفيضات prompt caching من Anthropic.
تشغيل مباشر من الخادم بدون جلسة مستخدم.
رؤية كاملة لرؤوس rate limit الخاصة بـ Anthropic.

إذا كنت تبني تدفقات Tool Use أو MCP معقدة، فقد تحتاج واجهة Anthropic الرسمية أو اختبار خادم MCP عبر Apidog.

متى تستخدم Puter؟ ومتى تستخدم Anthropic API الرسمية؟

استخدم Puter عندما:

تبني تطبيقًا يعمل من المتصفح.
تريد نموذجًا أوليًا سريعًا بدون إعداد مفاتيح وفوترة.
تنشر موقعًا ثابتًا أو مشروع هاكاثون.
تريد تجنب تحمل تكلفة استخدام المستخدمين.
لا تمانع أن يسجل المستخدم الدخول إلى Puter.

استخدم Anthropic API الرسمية عندما:

تحتاج استدعاءات Server-side.
لديك وظائف Cron أو معالجة دفعية.
تحتاج prompt caching لتقليل التكلفة.
تحتاج Tool Use متقدمًا أو Files API أو رؤية.
لديك متطلبات امتثال أو تعاقدات محددة.
لا تريد أن يمر المستخدم بخطوة تسجيل دخول إلى Puter.

يمكنك البدء بـ Puter ثم الترحيل لاحقًا إلى Anthropic API الرسمية؛ شكل الرسائل قريب بما يكفي لجعل الترحيل مباشرًا نسبيًا.

لمثال مشابه مع GPT، راجع: كيفية استخدام واجهة برمجة تطبيقات GPT-5.5.

اختبار التكامل في Apidog

لأن Puter يعمل من المتصفح، لن تختبره بنفس طريقة اختبار REST API خلفي. النمط العملي:

أنشئ صفحة HTML صغيرة تحتوي على Puter.js.
اجعل الصفحة تقرأ المطالبة من Query String.
اختبر Anthropic API الرسمية في Apidog كمسار بديل للإنتاج.
احتفظ ببيئتين منفصلتين: واحدة للنموذج الأولي وواحدة للإنتاج.

مثال صفحة اختبار بسيطة:

<!DOCTYPE html>
<html>
<body>
  <pre id="output"></pre>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    async function main() {
      const params = new URLSearchParams(location.search);
      const prompt = params.get("prompt") || "قل مرحبًا";

      const response = await puter.ai.chat(prompt, {
        model: "claude-sonnet-4-6"
      });

      document.querySelector("#output").textContent =
        response.message.content[0].text;
    }

    main();
  </script>
</body>
</html>

ثم افتحها بهذا الشكل:

http://localhost:5173/puter-test.html?prompt=اشرح%20JWT

قم بتنزيل Apidog، ثم أنشئ بيئتين:

puter-prototype: عنوان محلي يستضيف صفحة Puter.
anthropic-prod: https://api.anthropic.com/v1.

بهذا تستطيع مقارنة السلوك قبل الترحيل من Puter إلى Anthropic API الرسمية.

الأسئلة الشائعة

هل هذا غير محدود فعلًا؟

هو غير محدود من جهة المطور لأنك لا تدفع عن كل المستخدمين من حسابك. لكن المستخدم النهائي يعتمد على حساب Puter ورصيده الخاص.

هل أحتاج حساب Anthropic؟

لا. Puter يتولى الاتصال بـ Anthropic نيابة عن المستخدم.

هل يمكن استخدامه في الإنتاج؟

نعم لتطبيقات المتصفح، بشرط أن تكون تجربة تسجيل الدخول إلى Puter مقبولة لمستخدميك.

هل مخرجات Claude عبر Puter مختلفة عن Anthropic API؟

النموذج نفسه، لكن قد تختلف تفاصيل الواجهة أو زمن الاستجابة بسبب وجود طبقة Puter.

هل يدعم prompt caching؟

إذا كنت تحتاج خصائص Anthropic الرسمية مثل prompt caching لتقليل التكلفة، استخدم Anthropic API مباشرة.

هل يصلح لبوت Discord أو خدمة خلفية؟

ليس الخيار الأنسب. Puter مصمم أولًا لتدفقات المتصفح التي تتضمن جلسة مستخدم.

ما النموذج الافتراضي المقترح؟

ابدأ بـ claude-sonnet-4-6. استخدم claude-opus-4-7 للمهام الأصعب، وclaude-haiku-4-5 للمهام السريعة والبسيطة.

خاتمة

Puter.js يمنحك طريقة عملية لتشغيل Claude داخل تطبيقات المتصفح بدون إدارة مفاتيح API أو تحمل تكلفة الاستخدام عن المستخدمين. أضف السكريبت، اختر نموذجًا، أرسل الرسائل، وفعّل البث عند الحاجة.

إذا كان تطبيقك يحتاج خادمًا، وظائف خلفية، Tool Use متقدمًا، أو متطلبات امتثال، فواجهة Anthropic API الرسمية تبقى الخيار الأنسب.

للتجارب والمقارنات، أنشئ الطلب مرة واحدة في Apidog، اختبر Puter كنموذج أولي، ثم قارنه مع Anthropic API الرسمية قبل اتخاذ قرار الإنتاج.

DEV Community: Yusuf Khalidd

كيفية اختبار واجهات برمجة تطبيقات راست (Rust API)؟

ملخص سريع

لماذا تختبر Rust API خارج cargo test؟

الخطوة 1: أضف خادم Rust كبيئة في Apidog

الخطوة 2: أنشئ أول طلب

الخطوة 3: اختبر طلب واستجابة JSON باستخدام Serde

الخطوة 4: غطِّ حالات رفض Serde

الخطوة 5: اختبر المسارات المحمية بواسطة JWT

الخطوة 6: اختبر Streaming و Server-Sent Events

الخطوة 7: أنشئ Mock API لتطوير الواجهة الأمامية بالتوازي

الخطوة 8: احفظ الطلبات كسيناريو CI

الخطوة 9: أنشئ OpenAPI من الطلبات المحفوظة

الأسئلة الشائعة

هل يعمل Apidog مع Axum وActix-web؟

كيف أختبر المعالجات التي تتعطل؟

هل يمكن تشغيل Apidog ضد binary داخل Docker؟

ماذا عن gRPC؟

هل يغني ذلك عن cargo test؟

هل Apidog مجاني لمشاريع Rust مفتوحة المصدر؟

الخلاصة

حدود معدل استخدام API GPT: المستويات، قيود الاستخدام، وكيفية اختبارها باستخدام Apidog

القيود الأربعة التي تحتاج إلى قياسها

كيف تعمل المستويات

اقرأ حدودك الحالية من رؤوس الاستجابة

الخطوة 1: إنشاء طلب GPT في Apidog

الخطوة 2: تأكيد حد RPM بانفجار طلبات صغير

الخطوة 3: افصل RPM عن TPM

الخطوة 4: محاكاة مستخدمين متزامنين

ماذا تفعل عند ظهور 429

1. استخدم التراجع وإعادة المحاولة

2. ضع الطلبات في قائمة انتظار

3. استخدم Batch API للأعمال غير المتزامنة

أخطاء GPT 429 الشائعة

Rate limit reached ... on requests per min (RPM)

Rate limit reached ... on tokens per min (TPM)

You exceeded your current quota, please check your plan and billing details

قائمة تحقق سريعة قبل نشر ميزة تستخدم GPT

الأسئلة الشائعة

GPT-5.5 Pro ضد Instant: متى يكون دفع 6 أضعاف التكلفة مستحقًا؟

خلاصة القول (TL;DR)

مقدمة

النموذجان وراء عائلة GPT-5.5

مقارنة الأسعار

مقارنة الكمون

فارق الدقة: أين يتفوق إصدار Pro؟

متى تختار Pro؟

متى يكفي Instant؟

اختبار سريع للمقارنة بين Instant وPro

بناء تقييم محلي على طلباتك

حساب التكلفة: متى تكون 6 أضعاف مستحقة؟

الميزة 1: روبوت دعم العملاء

الميزة 2: مساعد مراجعة الكود

الميزة 3: ملخصات قانونية

قاعدة التعادل العملية

اختبر المفاضلة بين Pro وInstant باستخدام Apidog

1. أنشئ مشروعًا جديدًا

2. أضف طلبين إلى Responses API

3. طلب Instant

4. طلب Pro

5. اربط {{prompt}} بملف بيانات

6. التقط المقاييس

7. قارن النتائج

تقنيات عملية لتقليل التكلفة

1. وجّه حسب الميزة، لا حسب المستخدم

2. استخدم Pro كمسار تصعيد

3. فعّل التخزين المؤقت للطلبات

4. استخدم Batch للمهام غير الفورية

5. لا تملأ نافذة السياق بلا داعٍ

أخطاء شائعة

حالات استخدام واقعية

فرز مطالبات التأمين

مساعد مراجعة الكود

ملخصات قبول المستشفى

الخلاصة

الأسئلة الشائعة

التحقق من استجابات API في اختبارات بلاي رايت

ملخص سريع

لماذا لا تكفي اختبارات Playwright وحدها؟

البنية المقترحة

لماذا تختبر Rust API خارج `cargo test`؟

هل يغني ذلك عن `cargo test`؟

`Rate limit reached ... on requests per min (RPM)`

`Rate limit reached ... on tokens per min (TPM)`

`You exceeded your current quota, please check your plan and billing details`

5. اربط `{{prompt}}` بملف بيانات