حوّل طلبات الذكاء الاصطناعي متعدّدة الصيغ إلى مطالبات DeepSeek V4.1 باستعمال deepseek-recipe

شنو هو deepseek-recipe؟

deepseek-recipe هو مجموعة ديال مكتبات Rust وربطيات Python باش تربط خدمات API بخلفيات الاستدلال ديال DeepSeek. كيحوّل الطلبات من صيغ API المدعومة لتمثيل مشترك سميتو Conversation، وكيصيّغ هاد المحادثات فشكل prompts ديال DeepSeek V4 ولا V4.1، وكيحوّل خرج النموذج من جديد للصيغة المناسبة ديال الاستجابة.

هاد المشروع هو طبقة ديال البروتوكول ومعالجة الـ prompts، وماشي سيرفر كامل للاستدلال. خاصك توفّر الاستدلال ديال النموذج، والنقل عبر HTTP، وتنفيذ الأدوات بشكل منفصل.

كيفاش خدام خط المعالجة

1. كيستقبل طلب بصيغة Messages ولا Chat Completions ولا Responses.
2. كيحوّل الطلب للصيغة المشتركة ديال المكتبة، وهي Conversation.
3. كيصيّغ المحادثة فشكل prompt ديال DeepSeek V4 ولا V4.1، ولا كيشفّرها لمعرّفات ديال الرموز.
4. كيصيفط الـ prompt ولا معرّفات الرموز لخلفية استدلال خارجية.
5. كيحلّل الخرج المُولّد، بما فيه محتوى التفكير المدعوم، واستدعاءات الأدوات، وكائنات JSON، وتسلسلات التوقّف.
6. كيرجّع استجابة كاملة ولا متدفقة بالصيغة اللي كيتسناها العميل.

deepseek-recipe ما كيشغّلش النموذج، وما كينفّذش الأدوات، وما كيعرّضش خدمة HTTP بوحدو. كاينين سيرفرات نموذجية بـ Rust وPython فالمستودع باش تستعملهم كمراجع للتكامل.

الخصائص الرئيسية

• تحويل موحّد للبروتوكولات: كيتكلف بطلبات واستجابات Messages وChat Completions وResponses.
• ترميز prompts ديال DeepSeek: كيصيّغ محادثات DeepSeek V4 وV4.1 فشكل prompts ولا معرّفات ديال الرموز.
• استجابات متدفقة وكاملة: كيدعم تحويل جوج أنواع ديال الاستجابات.
• إعدادات التوليد: كينقل نمط التفكير، ومجهود الاستدلال، وtemperature، وtop_p، والحدود ديال رموز الخرج.
• تحليل الخرج: كيتعرّف على محتوى التفكير، واستدعاءات أدوات العميل، وخرج كائنات JSON، وتسلسلات التوقّف.
• الإدخال متعدد الوسائط: كيقبل الصور اللي كيتعطاو على شكل بيانات base64 ولا روابط خارجية. وحزمة الصور كتوفّر المعالجة القبلية ديال DeepSeek V4.1 باستعمال OpenCV.
• تعريفات الأدوات: كيدعم أدوات الدوال. وResponses API كيدعم زيادة على هاد الشي مساحات أسماء الأدوات والأداة المخصّصة apply_patch.

تثبيت وإعداد Python

المتطلبات

ربطيات Python كتحتاج Python 3.10 ولا أحدث. ثبّت الحزمة المنشورة باستعمال pip:

python3 -m pip install deepseek-recipe

الموديول المثبّت كتستوردو باسم deepseek_recipe.

تحويل طلب Chat Completions

المثال التالي كيبني طلب Chat Completions، وكيحوّلو لتمثيل Conversation المشترك، وكيصيّغ هاد المحادثة فشكل prompt ديال DeepSeek V4.1:

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
})

converted = request.convert(ConversionOptions())
rendered = DeepseekV41Encoding().render_conversation(
    converted.conversation
)

print(rendered.prompt)

فهم كل مرحلة

1. ChatCompletionRequest كيقرا بيانات Chat Completions الواردة.
2. request.convert(ConversionOptions()) كيوحّد الطلب فشكل Conversation.
3. DeepseekV41Encoding() كيختار قواعد الترميز ديال DeepSeek V4.1.
4. render_conversation كينشئ التمثيل الجاهز للنموذج.
5. rendered.prompt فيه الـ prompt اللي خاصك تصيفطو لخلفية الاستدلال الخارجية ديالك.

من بعد الاستدلال، استعمل مكوّنات تحويل الاستجابة وتحليل الخرج ديال المشروع باش تحوّل الخرج المُولّد ديال النموذج لصيغة API اللي كيحتاجها العميل ديالك. التكامل بالتحديد كيعتمد على واش الخلفية ديالك كترجّع الخرج كامل ولا ككتصيفط البيانات المُولّدة بشكل متدفق.

تثبيت وإعداد Rust

إضافة الحزم

زِد حزم تحويل البروتوكول والترميز لمشروع Rust:

cargo add deepseek-recipe@0.1 deepseek-recipe-encoding@0.1

إلى كنتي كاتبني من المصدر ولا مفعّل معالجة الصور، راجع دليل التطوير ديال المستودع باش تعرف تعليمات البناء وتبعيات الصور.

صياغة prompt ديال DeepSeek V4.1

use deepseek_recipe::openai::ChatCompletionRequest;
use deepseek_recipe::request::{ConversionOptions, ProtocolRequest};
use deepseek_recipe_encoding::PromptEncoding;
use deepseek_recipe_encoding::v4::dsv41::DeepseekV41Encoding;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request: ChatCompletionRequest = serde_json::from_value(json!({
        "model": "deepseek-flash",
        "messages": [
            {"role": "user", "content": "Hello"}
        ],
    }))?;

    let converted = request.convert(ConversionOptions::default())?;
    let rendered = DeepseekV41Encoding::new()
        .render_conversation(&converted.conversation);

    println!("{}", rendered.prompt);
    Ok(())
}

هنا، Serde كيدير إلغاء تسلسل JSON لــ ChatCompletionRequest. وtrait ديال ProtocolRequest كيوفّر تحويل الطلب، بينما PromptEncoding كيوفّر صياغة المحادثة. من بعد، يمكن تمرير الـ prompt الناتج لمحرك استدلال كتدبّرو بشكل منفصل.

اكتشاف عرض الترميز وفك الترميز

المستودع فيه واجهة ويب لصياغة prompts، وفحص الرموز الخاصة، وفك ترميز الخرج الكامل ديال النموذج لصيغ Chat Completions ولا Responses ولا Messages.

من جذر المستودع، شغّل:

cargo run -p encoding-decoding-demo --locked

من بعد حلّ http://127.0.0.1:7778 فالمتصفّح.

هاد العرض التجريبي مفيد باش تراجع بنية البرومبت وتفهم كيفاش كيترجع الخرج المولَّد لصيغ الاستجابة اللي كيدعمها الـ API، قبل ما تدمج المكتبات فالسيرفر.

نظرة عامة على الحزم

• deepseek-recipe: تحويل البروتوكولات وتحليل خرج النموذج.
• deepseek-recipe-core: الأنواع المشتركة ديال المحادثات، والرسائل، والصور، والأدوات.
• deepseek-recipe-encoding: عرض البرومبت وترميز التوكنات فـ DeepSeek V4 وV4.1.
• deepseek-recipe-image: جلب الصور والمعالجة القبلية ديالها.
• deepseek-recipe-python: ربطات Python المتاحة عبر الاستيراد deepseek_recipe.
• encoding-decoding-demo: فحص البرومبت والخرج عبر المتصفّح.
• server-rs: مثال ديال API بـ Axum كيستعمل استدلالاً وهمياً.
• server-py: مثال ديال FastAPI كيستعمل استدلالاً وهمياً.

نصائح متقدمة للدمج

خلي التعامل مع البروتوكول منفصل على الاستدلال

استعمل deepseek-recipe فحدود التطبيق ديالك. حوّل الطلبات الداخلة قبل الاستدلال وحلّل الخرج المولَّد من بعد. خلي تحميل النموذج، والتجميع، والجدولة، وتدبير العتاد داخل الواجهة الخلفية ديال الاستدلال.

اختار البرومبتات ولا معرّفات التوكنات بوعي

تقدر تعرض المحادثات كبرومبتات نصية ولا ترمّزها لمعرّفات التوكنات. استعمل عرض البرومبت إلا كانت الواجهة الخلفية ديالك كتقبل نصاً منسقاً. واستعمل ترميز التوكنات إلا كانت الواجهة الخلفية خدامة مباشرة بمعرّفات الـ tokenizer. دليل الـ tokenizer ديال المستودع كيشرح ترميز المحادثات وفك ترميز معرّفات توكنات الواجهة الخلفية.

خطّط للبث كميزة من البداية للنهاية

Rust وPython بجوج كيدعمو تحويل خرج النموذج لاستجابات متدفقة. خاص حتى طبقة النقل والواجهة الخلفية ديال الاستدلال ديالك تبثّ البيانات؛ المكتبة ما كتوفّرش هاد الطبقات. تبع دليل الاستجابات المتدفقة ملي تربط الخرج التدريجي ديال النموذج بـ API موجّه للعميل.

تعامل مع الصور قبل الاستدلال

الطلبات تقدر تشير للصور عبر المحتوى المشفّر بـ base64 ولا عبر روابط خارجية. مكوّن الصور المخصّص كيدعم جلب الصور والمعالجة القبلية ديال DeepSeek V4.1 باستعمال OpenCV. تأكّد باللي تبعيات الصور المطلوبة منصّبة ملي كتبني من المصدر.

خلي تنفيذ الأدوات خارج المكتبة

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

احترم الحدود الحالية

قبل ما تصمّم API مبني على المشروع، خذ بعين الاعتبار الميزات اللي مازال ما مدعومينش:

• احتمالات التوكنات عبر logprobs ولا top_logprobs.
• محتوى الوثائق، وإدخال الصوت ولا الفيديو، والاسترجاع باستعمال file_id.
• أدوات كينفّذها السيرفر بحال web_search.
• مخطط JSON وقيود الخرج بالتعابير النمطية.
• فرض إعدادات strict ديال الأدوات.
• اختيارات متعددة ديال Chat Completions ملي كيكون n > 1.
• تعريفات الأدوات المخصّصة ديال Responses باستثناء apply_patch.
• تخزين محادثات Responses ولا استرجاع السياق عبر previous_response_id.
• محتوى التفكير المشفّر عبر encrypted_content.

الخلاصة

deepseek-recipe كيوفّر مكوّنات قابلة لإعادة الاستعمال بـ Rust وPython لتوحيد عدة بروتوكولات ديال API، وإنشاء مدخلات DeepSeek V4 وV4.1، وترجمة الخرج المولَّد من جديد لاستجابات موجّهة للعميل. بدا بمثال تحويل الطلب الأساسي، وفحص السلوك عبر العرض التجريبي، ومن بعد ربط مسار التحويل بالبنية التحتية ديالك للاستدلال، والنقل، وتنفيذ الأدوات.

كود المشروع والوثائق العمومية متاحين بموجب رخصة MIT.