دليل ترحيل Claude Opus 4.7 - التغييرات الجذرية وطرق التعامل [النسخة الكاملة]

1. الفئة المستهدفة لهذا الدليل

كما أوضحنا في مقال إطلاق Claude Opus 4.7، Opus 4.7 هو الخلف المباشر لـ 4.6. لكن على مستوى API توجد عدة تغييرات جذرية متزامنة، وقد يسقط تبديل اسم النموذج فقط بـ 400 Bad Request في بعض الحالات.

هذا المقال موجّه لمن يلي:

• المطورون الذين يستدعون سلسلة claude-opus-4-6 عبر Anthropic API / SDK
• الفرق التي تستخدم Claude عبر Bedrock / Vertex AI
• من بقي على Opus 4.5 أو 4.1 ويريد القفز مرة واحدة إلى 4.7
• من يستخدم thinking: enabled أو temperature في الإنتاج

نعتمد دليل الترحيل الرسمي من Anthropic كمصدر أولي، مع التركيز على نقاط الاختناق في بيئات التطوير. للمعلومات الرسمية راجع دليل الترحيل على platform.claude.com.

2. خلاصة في 3 أسطر - أسرع فهم

TL;DR لمن ليس لديه وقت:

1. تبديل اسم النموذج من claude-opus-4-6 إلى claude-opus-4-7 (مع تحديث إصدار SDK)
2. التغييرات الجذرية 3 رئيسية: إلغاء التفكير الموسّع enabled (إلى التكيفي + effort)، إلغاء temperature/top_p/top_k، مُحلِّل توكنز جديد (حتى 1.35x للنص ذاته)
3. المكافأة: أداء برمجة أعلى، سياق 1M (بالسعر القياسي)، مستوى جهد جديد xhigh

التفاصيل في الفصول التالية.

3. تحديث اسم النموذج

أول ما تفعله بسيط: تبديل معرّف النموذج.

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

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

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

لكن تبديل اسم النموذج وحده لا يكفي في كثير من الحالات هذه المرة. نستعرض أدناه التغييرات الجذرية واحداً تلو الآخر.

4. التغيير الجذري 1: إلغاء التفكير الموسّع إلى التكيفي

في Opus 4.6 كنت تفعّل التفكير الموسّع (extended thinking) عبر thinking: {type: "enabled", budget_tokens: N}. في 4.7 هذا الشكل يُرجع خطأ 400.

بدلاً من ذلك، استخدم "التفكير التكيفي (adaptive thinking)" الذي يتحكم فيه النموذج بكمية التفكير تلقائياً. علاوة على ذلك التفكير افتراضي OFF في 4.7، فإن حذفت حقل thinking يعمل بدون تفكير. إن لم تفعّل صراحةً لن يقوم باستدلال عميق كالسابق.

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

نقاط مهمة

• لا حاجة للتحكم المباشر في "كمية التفكير" عبر budget_tokens
• بدلاً منه يُحدد "مدى الجدية في التفكير" عبر output_config.effort
• إن لم تضف حقل thinking أصلاً، يجيب فوراً بدون تفكير (انتبه: السلوك تغيّر عن 4.6)

5. التغيير الجذري 2: إلغاء معاملات العينات

تمرير قيم غير افتراضية لـ temperature أو top_p أو top_k يُرجع خطأ 400. هذا تطبيق صارم لمبدأ Anthropic "يُحدد سلوك النموذج عبر الموجه".

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k تُحذف تماماً
    messages=[...],
)

من كان يحصل على "إخراج مستقر قدر الإمكان" عبر temperature=0.2، ينبغي استبدالها بذكر صريح في الموجه مثل "أجب بأكبر قدر من الثبات لنفس السؤال"، أو باستخدام structured outputs عبر مخطط JSON.

أيضاً حالات temperature=1.2 لـ "الإبداع"، يُنصح بتضمين تعليمات نبرة في الموجه مثل "استخدم تعبيرات مجازية ومفاجئة".

6. التغيير الجذري 3: إخفاء محتوى التفكير افتراضياً

في 4.6 عند تفعيل التفكير كان "التفكير الملخص (summarized)" يتدفق افتراضياً في الاستجابة. كثير من التطبيقات تعرضه في الواجهة كـ "يفكر...".

في 4.7 تغيّرت المواصفات بهدوء، وتظهر كتلة التفكير في الاستجابة لكن حقل thinking فارغ. دون التفعيل الصريح لن تحصل على المحتوى.

العَرَض

في الواجهة يستمر مؤشر "يفكر..." في الدوران، ويبدو وقت بدء الإجابة طويلاً جداً. حين يقول المستخدم "هل تجمد؟" فهذه الحالة.

الحل

# إن أردت تمرير ملخص التفكير للواجهة كما في 4.6
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # حدد هذا صراحة
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

إن كانت المعالجة خلفية فقط ولا تعرض التفكير في الواجهة، فلا داعي لإضافة display ويمكن تركه.

7. التغيير الجذري 4: مُحلِّل توكنز جديد (~1.35x)

Opus 4.7 يعتمد مُحلِّل توكنز جديد داخلياً. يساهم في تحسين الأداء، لكن عدد التوكنز لنفس النص يزيد 1.0-1.35x مقابل 4.6 كأثر جانبي.

ماذا يسبب ذلك:

• العمليات المُعدّة على حافة max_tokens قد تُقطع في المنتصف
• تقديرات ما يُعادل tiktoken في العميل للفوترة وفحص الطول تصبح غير دقيقة
• نتائج /v1/messages/count_tokens تختلف بين 4.7 و 4.6
• زيادة طفيفة في التكلفة والكمون لنفس الموجه

الحل

# Before: افتراض 4.6 مع احتياطي إخراج 16k توكن
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: هامش 1.35x
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ≒ 21600 → تقريب لأعلى
    messages=[...],
)

أيضاً في 4.7 نافذة سياق 1M متاحة بالسعر القياسي (بدون علاوة للسياق الطويل). رغم زيادة توكنز المحتوى، صار من الأسهل تبنّي استراتيجية "ضع كل شيء في الإدخال".

8. التغيير الجذري 5: إلغاء التعبئة المسبقة

تغيير جذري مستمر من 4.6. التعبئة المسبقة لرسائل assistant - أي وضع رسالة مثل {role: "assistant", content: "```json"} في ذيل مصفوفة messages لإجبار "إجابة تبدأ بـ JSON" - تُرجع خطأ 400.

# Before: إجبار إخراج JSON بالتعبئة المسبقة
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "أرجع معلومات المستخدم بصيغة JSON"},
        {"role": "assistant", "content": "```json\n{"},  # تعبئة مسبقة
    ],
)

# After: استخدم structured outputs
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "أرجع معلومات المستخدم بصيغة JSON"},
    ],
)

توجد ثلاثة بدائل للتعبئة المسبقة:

1. Structured outputs (output_config.format) - تقييد تنسيق الإخراج بمخطط JSON
2. موجه النظام يحدد "أرجع JSON فقط، دون markdown أو مقدمات"
3. Tool use للاستقبال كاستدعاء دالة (الوسائط ستكون JSON مهيكلاً)

9. كيفية اختيار مستوى الجهد (xhigh جديد)

قيم output_config.effort خمس مستويات. xhigh جديد في 4.7.

من كان يحدد budget_tokens يدوياً في عصر 4.6، يكتفي باختيار effort في 4.7. القاعدة التجريبية للاستخدام:

• وكيل برمجة (Claude Code) ابدأ من xhigh
• دردشة Q&A أو استجابة RAG، high خيار آمن
• عمال خفيفون (وسوم، استخراج JSON، تصنيف) medium أو low
• max مقتصر على "سؤال واحد أريد التفكير فيه بعمق مهما كلف"

10. التعامل مع تغيّر السلوك

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

10.1 طول الاستجابة يتكيف مع المهمة

4.7 يضبط طول الاستجابة تلقائياً حسب تعقيد المهمة. لم يعد هناك طول ثابت مثل "اكتب في 3 فقرات دائماً". بمعنى، يُنصح بحذف موجهات التحكم في الطول القائمة والتحقق من السلوك الجديد.

10.2 يأخذ التعليمات حرفياً أكثر

خصوصاً عند انخفاض effort. "بإيجاز" يعيد بإيجاز فعلاً، و "اذكر 3" لن يضيف رابعاً. خاصية مفيدة لكن سلوك 4.6 "قراءة ما بين السطور وإكمال التعليمات الغامضة" تراجع.

10.3 نبرة أكثر مباشرة

قلّت عبارات التحقق "سؤال رائع!" والرموز التعبيرية التزيينية والتحيات المُفتتحة. للحفاظ على نبرة ودية، حدد النبرة في موجه النظام.

10.4 تحديثات التقدم مدمجة في تتبع الوكلاء

إن كنت تبني سقالة يدوية لـ "سأفعل كذا الآن"، "أفعل كذا حالياً" في تشغيل الوكلاء، فـ 4.7 يُخرج ذلك داخلياً، ويمكنك إزالة السقالات المكررة.

10.5 الوكلاء الفرعيون واستدعاءات الأدوات أقل

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

10.6 حماية أمن سيبراني لحظية

حتى الأعمال المشروعة للأمن الهجومي (فرق حمراء، PoC ثغرات) قد تُرفض حسب السياق. إن كان الأمن حالة استخدام إنتاجية لديك، فكر في التقدم لـ برنامج التحقق السيبراني (cyber verification program) من Anthropic.

10.7 دعم الصور عالية الدقة

معالجة الصور حتى 2576px مباشرة أصبحت ممكنة. لكن الصورة بالدقة الكاملة تستهلك حوالي 3 أضعاف التوكنز. للأحمال الكثيفة بالصور، اختر (a) إعادة توزيع max_tokens، أو (b) تقليل الدقة قبل الإرسال.

11. التغييرات المستحبة (غير إلزامية)

من هنا بنود "يعمل بدونها لكنك تكسب إن فعلتها":

1. إعادة تقييم max_tokens: مع توسع جانب الإخراج بالمُحلِّل الجديد، ابدأ من قيمة مضاعفة 1.2-1.35x وأعد التحقق
2. تدقيق تقدير التوكنز في العميل: إن كنت تحسب الفوترة أو تفحص الطول ذاتياً، اعتمد على API count_tokens أو راجع المعاملات
3. تبني task_budgets (بيتا): لتشغيل الوكلاء. أضف ترويسة task-budgets-2026-03-13 والحد الأدنى 20k. انتبه أنها "حد إرشادي" وليست "سقف صارم"
4. ضبط max_tokens على 64k أو أكثر: عند استخدام xhigh/max، يُنصح بـ 64k فأكثر لمجموع التفكير والإخراج
5. تقليل دقة الصور: إن لم تكن الدقة العالية ضرورية، قلّصها قبل الإرسال لتوفير توكنز وتكلفة

11.1 أصغر مثال لـ task_budgets (Python SDK الرسمي)

task_budgets ميزة بيتا، لذا استخدم نقطة النهاية client.beta.messages.create، وحدد betas صراحة. طريقة الاستدعاء تختلف عن ميزات GA.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

نقاط المواصفات:

• الحد الأدنى 20,000 توكن. لا تُقبل قيم أدنى
• max_tokens سقف صارم لكل طلب (غير ظاهر للنموذج)، task_budget حد إرشادي لكامل حلقة الوكيل (النموذج يعرف العد التنازلي)
• للتحكم الصارم بالتكلفة: max_tokens. للتوازن بين الجودة والكفاءة: task_budget
• للمهام المفتوحة حيث الجودة > السرعة، يُنصح بعدم ضبط task_budget (يميل للاختصار الزائد)

12. الترحيل من Opus 4.5 أو 4.1 فما سبق

إن كنت تقفز من 4.5 أو 4.1 مباشرة إلى 4.7 دون المرور بـ 4.6، أضف للتعامل السابق:

• إزالة معاملات العينات: مستخدمو Claude 3.x يستعملون temperature بشكل اعتيادي. إزالة كاملة
• تنظيف ترويسات beta: مثل effort-2025-11-24 و fine-grained-tool-streaming-2025-05-14 و interleaved-thinking-2025-05-14 اندمجت في الجوهر، احذفها
• تبديل نقاط النهاية: غيّر من client.beta.messages.create إلى client.messages.create
• الانتقال من output_format إلى output_config.format: تغيّر اسم المفتاح
• تحليل وسائط الأدوات: منذ 4.6 يختلف سلوك تهريب JSON في بعض الحالات. استخدم JSON.parse / json.loads بدل تحليل السلسلة الخام

للمزايا الجديدة في Claude Opus 4.7 ذاته، راجع المقال السابق Claude Opus 4.7: المزايا الجديدة والمعايير والأسعار.

13. قائمة تحقق الترحيل (كل البنود)

قائمة للطباعة والتوزيع على الفريق، جميع البنود مرتبة:

13.1 إلزامي (بدونها خطأ 400 أو انكسار سلوكي)

• ☐ تحديث اسم النموذج claude-opus-4-6 ← claude-opus-4-7
• ☐ حذف temperature / top_p / top_k
• ☐ استبدال thinking: {type: "enabled", budget_tokens: N} بـ {type: "adaptive"} + output_config.effort
• ☐ حذف التعبئة المسبقة لرسائل assistant واستبدالها بـ structured outputs / موجه النظام
• ☐ إن كنت تعرض التفكير في الواجهة، حدد thinking.display: "summarized" صراحة

13.2 ضبط (تحسين التكلفة والجودة)

• ☐ إعادة قياس التكلفة والكمون مع المُحلِّل الجديد
• ☐ ضبط max_tokens بمعامل 1.35x
• ☐ إعادة اختبار منطق تقدير التوكنز في العميل
• ☐ عند إرسال صور، إعادة توزيع توكنز للدقة العالية
• ☐ عند استخدام xhigh/max، ضبط max_tokens ≥ 64k
• ☐ للأحمال الوكيلية، دراسة تبني task_budgets (بيتا)

13.3 مراجعة الموجهات والتشغيل

• ☐ التحقق من تكيف الطول والتفسير الحرفي وتغير النبرة على موجهات حقيقية
• ☐ حذف موجهات التحكم في الطول وإعادة قياس خط الأساس
• ☐ التقدم لبرنامج التحقق السيبراني عند الرفض في أعمال الأمن
• ☐ تبسيط سقالات الوكلاء (إخراج تقدم وسيط) التي أصبحت مكررة
• ☐ للترحيل من 4.5 أو أقدم: حذف ترويسات beta والانتقال إلى client.messages.create

14. أداة الترحيل التلقائي

إن كنت تستخدم Claude Code، يمكنك أتمتة التعديل الآلي عبر مهارة Claude API التي توفرها Anthropic. تستدعي المهارة في Claude Code كالتالي:

/claude-api migrate

رحّل المشروع كاملاً من Claude Opus 4.6 إلى 4.7.
- بدّل اسم النموذج
- احذف temperature / top_p / top_k
- استبدل thinking: enabled بـ adaptive + effort: high
- إن بقيت تعبئة مسبقة، استبدلها بـ structured outputs

المهارة تفحص المستودع، تحدد الملفات التي تستورد SDK anthropic، ثم تقترح التعديلات. لكن لا تؤتمت تعديلات نصوص الموجهات أو إعادة قياس البنشمارك، فلا بد من إنهاء الأمر بالقائمة يدوياً.

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

أُعد هذا المقال بناءً على دليل الترحيل الرسمي لـ Claude Opus 4.7 من Anthropic (في أبريل 2026). قد تتغير مواصفات API، لذا تحقق من أحدث معلومات التوثيق الرسمي قبل الإنتاج.