Ultrafast: التثبيت والتشغيل — uv sync مع مفتاحي API
فكّك الدرس السابق Jev Ultrafast: المبادئ بالكامل، وهذا الدرس عملي: ستثبّت jev-ultrafast على حاسوبك وتشغّل inspector المحلي. ما عليك سوى أمرين — uv sync لتثبيت البيئة، و .env لإدخال مفتاحي API.
مسار التثبيت في README الرسمي يتكون من 5 أوامر (git clone و cd و uv sync و cp و uv run jev)، والأوامر نفسها ليست صعبة — لكن خلف كل أمر «لماذا»: لماذا uv وليس pip، وما الذي يديره كل مفتاح، ومتى يتصل Chrome. سنخصص 15 دقيقة لذلك هنا، وبعد التثبيت ننتقل مباشرة إلى الدرس التالي لتشغيل Google Flights حقيقيًا.
ماذا ستستطيع أن تفعل بعد الدرس
- إكمال تثبيت jev-ultrafast باستخدام
git clone+uv sync، مع تثبيت التبعيات المثبّتة فيuv.lockالمرفق بالمستودع وتثبيتها في.venvبجانب المشروع دون المساس بـ Python الخاص بالنظام - إعداد 6 متغير بيئة في
.env، مع توضيح المفتاحين الإلزاميين وأي استدعاء يخدمه كل منهما - فتح inspector على
127.0.0.1:8766وتشغيل أول demo عبر Start demo → Run automatically - الاتصال بـ Chrome باستخدام
uv run browser-harness --doctor، ومعرفة ما إذا كان يجب النقر على مطالبة «السماح بالتصحيح عن بُعد» - استبدال helper النص من OpenRouter + Mercury في المثال بـ DeepSeek أو GLM أو غيرها من النماذج المتوافقة مع OpenAI
مشكلتك الحالية
- تريد أن ترى بعينك البحث عن الرحلات في 7 ثوانٍ، لكن README يحتوي على خمسة أسطر من الأوامر فقط، وعندما لا يعمل شيء لا تعرف أي طبقة تفحص: هل لم يُثبَّت، أم المفتاح غير مُعد، أم Chrome غير متصل
- المفاتيح مربكة قليلًا: لديك مفتاح TypeSafe، لكن الإعدادات النموذجية تتطلب مفتاح OpenRouter أيضًا — ماذا يحدث إذا نقص أحدهما، ومتى يظهر الخطأ بالضبط، لست واثقًا
- على حاسوبك إصدارات Python كثيرة، ويطلب هذا المستودع Python ≥ 3.12 — لا تريد التعامل يدويًا مع بيئة عامة أخرى
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- تشغيل النسخة المفتوحة المصدر من Jev Ultrafast على جهازك، لتهيئة البيئة لـ تشغيل Google Flights
- رؤية العناصر المرقّمة واحتمالات الإجراءات واحتمالات الأهداف التي شرحها الدرس السابق بعينك في inspector — المبادئ تتحول إلى صورة
- لاحقًا كتابة مهام متصفح خاصة بك باستخدام مكتبة الوكيل (Agent)
ولا تريد:
- إنشاء venv يدويًا وتثبيت التبعيات بـ pip ومعالجة تعارضات الإصدارات
- تثبيت مفاتيح API مباشرة في الكود، أو رفعها إلى git عن طريق الخطأ
🎒 تجهيزات قبل البدء
- إكمال Jev Ultrafast: المبادئ: معرفة مجموعة الإجراءات و speculative target heads وحدود السلامة، حتى لا تتوه عند مشاهدة inspector بعد التثبيت
- امتلاك مفتاح TypeSafe API (إن لم يكن لديك، فاتبع أولًا التسجيل ومفتاح API)
- تثبيت Chrome على حاسوبك — كل نقرات وإدخالات الوكيل تحدث داخل Chrome
- (اختياري) مفتاح حساب OpenRouter، أو استخدام مفتاح DeepSeek / GLM مباشرة (ستشرح الخطوة 3 كيفية الاستبدال)
- كوب من الماء — هذه المرة ستترك فعلًا Jev ينقر المتصفح نيابةً عنك
متطلبات النظام
| العنصر | المتطلب | المصدر |
|---|---|---|
| Python | ≥ 3.12 (requires-python = ">=3.12") | ملف pyproject.toml في المستودع |
| uv | أي إصدار متاح، وإن لم يوجد فثبّته في الخطوة 1 | يثبّت README التبعيات عبر uv sync |
| Chrome | مثبّت محليًا، مع السماح بالتصحيح عن بُعد أثناء التشغيل | قسم «Try it» في README |
| الشبكة | القدرة على الوصول إلى api.typesafe.ai ونقطة نهاية نموذج النص الذي تُعدّه | jev_ultrafast/model.py |
💡 ما هو uv
uv هو مدير حزم ومشاريع Python من Astral (النص الرسمي: extremely fast Python package and project manager, written in Rust). وهو يحافظ على بيئة .venv خاصة بالمشروع بجانب pyproject.toml، ويتحقق uv run في كل مرة أولًا من أن البيئة وملف القفل متزامنان—لن تحتاج بعد الآن إلى تفعيل أي شيء يدويًا. سبق أن استخدمنا uv add في طريقة تثبيت بديلة لـ SDK، وهذه المرة نستخدم أمره الشقيق uv sync.
الفكرة الأساسية
جوهر تثبيت jev-ultrafast = مجموعة تبعيات مُقفلة + مفتاحان.
التبعيات تُسند إلى uv sync. هذا المستودع يأتي أصلًا مع pyproject.toml وuv.lock، ويقوم uv sync بأمرين (بحسب تعريف وثائق uv الرسمية في قسم «Locking and syncing»): قفل التبعيات في ملف قفل، ثم تثبيت الحزم من ملف القفل داخل بيئة المشروع (وهي .venv بجانب pyproject.toml). النواتج الأساسية الثلاثة من التثبيت:
| ما يُثبَّت في .venv | قيود الإصدار | الغرض |
|---|---|---|
jev-ultrafast الحزمة الأساسية | 0.1.0 | حلقة agent + نقطة دخول أمر jev |
browser-harness | == 0.1.13 | الاتصال بـ Chrome (README: يُثبَّت تلقائيًا بواسطة uv sync) |
httpx[http2] | ≥ 0.28, < 1 | عميل HTTP لإرسال TypeSafe وطلبات النماذج النصية |
تبعيات التطوير (pytest وruff وpillow) تنتمي إلى مجموعة dev، ويثبّتها uv sync افتراضيًا مع البقية—لا داعي للانشغال بها.
المفاتيح تُوضع في .env، وهناك مفتاحان إجمالًا. لماذا مفتاحان؟ كما ذكرنا في الدرس السابق: Jev يقوم بالقرارات فقط ولا يولّد النصوص؛ وعند مواجهة عملية TYPE_TEXT، تُولَّد السلاسل النصية بواسطة «LLM صغير» مستقل. لذلك هناك خدمتان مستقلتان يحتاج كل منهما إلى تفويض:
| المفتاح | من يفوّض | متى يُستخدم |
|---|---|---|
TYPESAFE_API_KEY | api.typesafe.ai/v1/systemone (Jev للقرارات) | يُستخدم في كل دورة قرار، وبدونه لا يُرسل أول طلب أصلًا |
TEXT_MODEL_API_KEY | نقطة نهاية متوافقة مع OpenAI يشير إليها TEXT_MODEL_BASE_URL (المثال هو OpenRouter) | فقط عندما تكون العملية من نوع TYPE_TEXT، وبدونه يظهر الخطأ عند خطوة الكتابة فقط |
هذا التقسيم «طلب واحد لسؤال عن العملية، وكتابة النص مُسندة إلى نموذج صغير» هو التطبيق العملي للتوزيع الاستباقي (speculative fan-out) في الأسئلة المتوازية بـ Jev.
أخيرًا هناك اختيار طريقة التشغيل—بعد التثبيت أمامك ثلاث طرق، ونسلك في هذا الدرس الطريقة الأولى:
| طريقة التشغيل | لمن تصلح |
|---|---|
تجربة محلية (uv run jev + inspector) | لمن يريد نظرة سريعة أولًا مع إمكانية الإيقاف خطوة بخطوة—هذا الدرس |
مكتبة Agent (uv run --env-file .env python 你的脚本.py) | لمن يريد كتابة مهامه الخاصة—الدرس 5 |
خدمة BU Ultrafast السحابية (model: "bu-ultrafast") | لمن لا يريد تثبيت أي شيء وتشغيله مباشرة على Browser Use Cloud |
طبّق معي
الخطوة 1: ثبّت uv وChrome—المتطلب السابق لتثبيت jev-ultrafast
لماذا: يتم التثبيت كله بأمر uv واحد؛ أما Chrome فهو «يد» الـ agent، فكل النقر والإدخال يحدثان بداخله.
تأكد أولًا من وجود uv:
uv --versionينبغي أن ترى: سطرًا يحمل رقم الإصدار (مثل uv 0.13.x، والاعتبار للإصدار الذي ثبّته أنت). إن لم يظهر، ففي macOS / Linux استخدم سكربت التثبيت الرسمي:
curl -LsSf https://astral.sh/uv/install.sh | shفي Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"هذه الأوامر كلها من وثائق التثبيت الرسمية لـ uv (docs.astral.sh/uv)؛ ويمكن أيضًا استخدام مديري حزم مثل brew install uv وpipx install uv وwinget install --id=astral-sh.uv -e. وإذا لم يكن curl متوفرًا في نظامك، توفر الجهة الرسمية نسخة بـ wget: wget -qO- https://astral.sh/uv/install.sh | sh.
لا حاجة لتغيير أي إعدادات في Chrome، يكفي أن يكون مثبتًا—فإشارة تفويض التصحيح عن بُعد لن تظهر إلا في الخطوة 5.
uv --versionيعطي مخرجات؛ ويفتح Chrome بشكل طبيعي
الخطوة 2: git clone ثم تشغيل uv sync—تثبيت jev-ultrafast نفسه
لماذا: أوامر التثبيت في قسم «Try it» من README هي هذه فقط، انسخها حرفيًا؛ وسيقوم uv sync بتثبيت كل التبعيات المُقفلة في المستودع دفعة واحدة (بما فيها Browser Harness)، دون حاجة إلى pip لكل حزمة.
git clone https://github.com/browser-use/jev-ultrafast.git
cd jev-ultrafast
uv syncينبغي أن ترى: يستنسخ git المستودع إلى دليل jev-ultrafast/؛ ويكمل uv تحليل التبعيات وتثبيتها، وتُدرج المخرجات الحزم المثبتة في البيئة (ومنها ينبغي أن ترى browser-harness وhttpx)؛ ويظهر دليل .venv/ داخل دليل المستودع.
ثلاثة تفاصيل يستحق معرفتها (استنادًا إلى وثائق uv الرسمية):
| التفصيل | الشرح |
|---|---|
.venv/ | بيئة المشروع التي يديرها uv بجانب pyproject.toml، فلا تلوّث Python النظامية ولا تحتاج إلى تفعيل يدوي |
uv.lock | مرفق مع المستودع ويقفل إصدارات دقيقة؛ وعند وجود ملف قفل مسبقًا يعطي uv sync الأولوية للإصدارات المُقفلة |
uv run يزامن تلقائيًا | قبل كل uv run … يتأكد من أن البيئة وملف القفل محدّثان، لذا حتى لو عدّلت التبعيات فلا حاجة لإعادة sync يدويًا |
uv syncبدون أخطاء، وتستطيع رؤية.venv/تحتjev-ultrafast/
الخطوة 3: انسخ .env.example وضع فيه مفتاحي API
لماذا: تمر جميع المفاتيح عبر ملف .env—فهو مُتجاهَل في السطر الأول من .gitignore الخاص بالمستودع، ويذكر قسم التطوير في README صراحة «Credentials and raw traces stay ignored»، فالمفاتيح لن تنتقل مع git.
cp .env.example .envثم افتح .env وضع المفتاحين (القيمة <尖括号> مجرد عنصر نائب، احذف أقواس الزوايا بعد التعبئة):
TYPESAFE_API_KEY=<你的 TypeSafe API Key>
TYPESAFE_MODEL=jev-latest
TEXT_MODEL_API_KEY=<你的文本模型 Key>
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL=inception/mercury-2.5
TEXT_MODEL_REASONING=noneفي .env.example إجمالًا 6 متغيرات، وإليك شرح كل منها (القيم النموذجية والافتراضية كلها من هذا الملف ومن jev_ultrafast/model.py):
| المتغير | القيمة النموذجية | مطلوب؟ | ما الذي يتحكم فيه |
|---|---|---|---|
TYPESAFE_API_KEY | — | مطلوب | مفتاح Bearer لطلبات قرارات Jev، يُرسل إلى api.typesafe.ai/v1/systemone |
TYPESAFE_MODEL | jev-latest | يمكن حذفه | نموذج القرار؛ عند عدم تعيينه يعتمد الكود افتراضيًا أيضًا jev-latest |
TEXT_MODEL_API_KEY | — | TYPE_TEXT ضروري | مفتاح مساعد النصوص؛ إذا لم يُعيَّن وتمت مواجهة عملية كتابة فسيُرمى خطأ مباشرة |
TEXT_MODEL_BASE_URL | https://openrouter.ai/api/v1 | يمكن حذفه | نقطة نهاية نموذج النصوص؛ عند عدم تعيينها يعتمد الكود افتراضيًا https://api.deepseek.com/v1 |
TEXT_MODEL | inception/mercury-2.5 | يمكن حذفه | اسم نموذج النصوص؛ عند عدم تعيينه يعتمد الكود افتراضيًا deepseek-chat |
TEXT_MODEL_REASONING | none | يمكن حذفه | none = إيقاف الاستدلال؛ قواعد الحالة غير المعيَّنة موضحة أدناه في الطريقة B |
مصدر المفتاحين: مفتاح TypeSafe احصل عليه من console.typesafe.ai/keys (مرَّت به في درس التسجيل)؛ أما مفتاح نموذج النصوص فيعتمد على الطريقة التي تختارها:
الطريقة A (الإعداد النموذجي): OpenRouter + Mercury
.env.example بالإعداد كما هو: مفتاح OpenRouter + inception/mercury-2.5، مع إيقاف الاستدلال. يقول README إن العرض التجريبي الحالي يستخدمه كما هو. انسخه مباشرة، بلا أي كلفة قرار.
الطريقة B: اتصال مباشر بـ DeepSeek — نقطة النهاية الافتراضية في الكود
املأ TEXT_MODEL_API_KEY=<你的 DeepSeek Key> فقط، ويمكن ترك سطري TEXT_MODEL_BASE_URL وTEXT_MODEL دون كتابة (إذا نسخت من .env.example فيجب حذف هذين السطرين، وتركهما فارغين لا يجوز أيضًا — فالسلسلة الفارغة تُحتسب أيضًا كإعداد) — القيمة الافتراضية عند unset في model.py هي https://api.deepseek.com/v1 + deepseek-chat. يتم التعرف على نقطة نهاية DeepSeek تلقائيًا، ويُرفق thinking: {type: disabled} في الطلب لإيقاف الاستدلال.
الطريقة C: GLM / Gemini وغيرها من النماذج المتوافقة مع OpenAI
يقول README صراحةً: يمكن استخدام Gemini وGLM وDeepSeek جميعها مع مساعد النصوص المتوافق مع OpenAI هذا — «اضبط model وendpoint وreasoning وفقًا لذلك». أي استبدل TEXT_MODEL_BASE_URL بنقطة النهاية المتوافقة مع OpenAI للخدمة التي تستخدمها، وTEXT_MODEL باسم النموذج المقابل (القيم المحددة تُعتمد وفقًا لوثائق مزود الخدمة لديك).
⚠️ قواعد معامل reasoning
منطق model.py هو: عندما تحتوي نقطة النهاية على api.deepseek.com/ يُرفق thinking: {type: disabled} تلقائيًا؛ ونقاط النهاية الأخرى ترفق reasoning: {effort: low} افتراضيًا؛ وفقط عند TEXT_MODEL_REASONING=none يصبح reasoning: {enabled: false}. عند تغيير النموذج، ترك سطر TEXT_MODEL_REASONING=none هو الأسهل.
يجب أن ترى: في .env المفتوح، كلا سطري TYPESAFE_API_KEY وTEXT_MODEL_API_KEY يحملان قيمك الخاصة، وقد حُذفت أقواس الزوايا النائبة؛ أما أسطر 4 الأخرى فتبقى على القيم النموذجية أو تُعدَّل وفق الطريقة B/C.
.envالمفتاحان فيه غير فارغين؛ تأكد أنه موجود في.gitignore(مُستثنى افتراضيًا)
الخطوة 4: تشغيل uv run jev لبدء inspector المحلي
لماذا: jev هو نقطة الدخول عبر سطر الأوامر التي سجّلها pyproject.toml (في [project.scripts] هو jev = "jev_ultrafast.demo:main")، ويشغّل صفحة inspector ** تستمع فقط إلى عنوان الاسترجاع المحلي **.
شغّل في الدليل الجذري للمستودع:
uv run jevيجب أن ترى (الإخراج في الطرفية كما هو، من demo.py في main()):
Jev Ultrafast: http://127.0.0.1:8766افتح في المتصفح http://127.0.0.1:8766، وسترى الصفحة الرئيسية للعرض التجريبي: حقل إدخال المهمة، وقائمة منسدلة للمشاهد، وصف من أزرار التحكم. هذه الخدمة مرتبطة بـ 127.0.0.1 فقط (تُعرّف docstring في demo.py نفسها بأنها Loopback-only inspector)، ولا يمكن للأجهزة الأخرى الوصول إليها؛ أوقفها بـ Ctrl+C.
تفصيلان:
المنفذ الافتراضي 8766، وإذا كان مشغولًا يمكن تغييره عبر متغير البيئة
TYPESAFE_DEMO_PORT(انظر النصائح المتقدمة).envيُقرأ عند بدء التشغيل منالدليل الحالي — لذلك يجب تشغيل هذا الأمر داخلjev-ultrafast/الدليل الجذري للمستودع (السبب في تنبيه المخاطر رقم 2)الطرفية تطبع
Jev Ultrafast: http://127.0.0.1:8766، ويمكن رؤية الصفحة في المتصفح
الخطوة 5: Start demo يتصل بـ Chrome ويُنجح أول عرض تجريبي
لماذا: inspector هو اللوحة الرسمية التي تُريك عملية القرار؛ عند النقر على Start demo لأول مرة، سيقوم Browser Harness بالاتصال بـ Chrome — وهنا يظهر موجه تفويض التنقيح عن بُعد.
على الصفحة (أسماء الأزرار هي النصوص الأصلية للواجهة):
- تمت تعبئة الهدف الافتراضي مسبقًا في حقل المهمة: البحث عن رحلة طيران من Zurich إلى London باتجاه واحد (انظر النص الأصلي في
static/index.html، ويمكنك تغييره إلى هدفك الخاص المكوَّن من 1–2000 حرفًا) - اختر من القائمة المنسدلة للمشاهد
Google Flights · real web(المشهدان الآخرانTravel planner · fixtureوReading room · fixtureصفحات محلية لا تتصل بالإنترنت) - انقر Start demo
- عندما يطلب Chrome تفويض التنقيح عن بُعداسمح (النص الأصلي في README: Allow remote debugging in Chrome when prompted)
- انقر Run automatically لبدء التشغيل؛ وإذا أردت المتابعة خطوة بخطوة فانقر Choose next، وسيتوقف قبل كل تنفيذ
إذا لم يتصل Chrome، فشغّل في طرفية أخرى (في الدليل الجذري للمستودع):
uv run browser-harness --doctorيجب أن ترى: في لوحة inspector تظهر العناصر المرقّمة واحتمالات العمليات واحتمالات الأهداف والإجراءات المنفَّذة (الأشياء الأربعة بنص README الأصلي)؛ وفي لوحة المتصفح تبدأ الصفحة في العمل التلقائي. بعد الانتهاء أوقف الخدمة بـ Ctrl+C.
- بعد Start demo تظهر في inspector العناصر المرقّمة وعمودا الاحتمالات؛ وفي نافذة Chrome تتحرك الصفحة
نقطة تحقق ✅
uv --versionيعطي إخراجًا، وChrome مثبَّتuv syncبلا أخطاء، ويوجد.venv/في دليل المستودع، وتتضمن قائمة التثبيتbrowser-harness.envتم ملء المفتاحين:TYPESAFE_API_KEYوTEXT_MODEL_API_KEY- من الدليل الجذري للمستودع نفّذ
uv run jevوسيُطبعJev Ultrafast: http://127.0.0.1:8766 - افتح
127.0.0.1:8766في المتصفح، وبعد Start demo سترى العناصر المرقّمة واحتمالات العمليات والاحتمالات المستهدفة
تنبيهات للمزالق
❌ بدء التشغيل بعد ملء TYPESAFE_API_KEY فقط
الأعراض: يمكن تشغيل demo ويمكن ملاحظة الصفحة، لكنه يتوقف عند خطوة «الكتابة في مربع الإدخال»، ورسالة الخطأ نصًّا كما يلي:
TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor.السبب: لا يتم التحقق من TEXT_MODEL_API_KEY إلا عندما تكون العملية من نوع TYPE_TEXT (داخل model.py عبر field_text())، ولا يُتحقق عند بدء التشغيل، لذا يمكن أن يستمر التشغيل بدون مفتاح حتى ينفجر عند الكتابة. عرض Flights demo يحتاج إلى توليد أسماء المدن، فلا مفر منه إطلاقًا.
الطريقة الصحيحة: تهيئة المفتاحين معًا دفعة واحدة — وهذا بالضبط معنى «مفتاحا API» في الدرس H1.
❌ التشغيل خارج الدليل الجذري للمستودع فلا يُقرأ .env
الأعراض: رغم ملء المفتاح، ما زال يُبلَّغ عن نقصه أو تُستخدم تهيئة قديمة.
السبب: تقرأ demo.py عبر load_environment() ملف .env مندليل العمل الحالي (الكود هو حرفيًا Path.cwd() / ".env")، فعند تشغيل uv run jev في دليل آخر يُقرأ .env من مكان آخر (أو لا يُقرأ أصلًا). كما أنها تستخدم setdefault — فإذا كنت قد نفّذت export سابقًا لمتغيّر بالاسم نفسه في طرفيتك، فإن القيمة في .env لن تتجاوزه.
الطريقة الصحيحة: نفّذ cd jev-ultrafast أولًا ثم uv run jev؛ وعند استكشاف الأخطاء استخدم echo $TEXT_MODEL_API_KEY لترى ما إذا كانت هناك قيمة قديمة في الصدفة سبقت ذلك.
❌ Chrome لا يتصل واللوحة لا تتحرك أبدًا
السبب: يحتاج Browser Harness إلى السماح لـ Chrome بالتصحيح عن بُعد، وسيظهر Chrome تنبيهًا عند الاتصال الأول؛ وإذا فوّته أو رفضته فلن يتم الاتصال.
الطريقة الصحيحة: شغّل uv run browser-harness --doctor لتشخيص الاتصال؛ وفي المرة القادمة التي يظهر فيها Chrome تنبيه «السماح بالتصحيح عن بُعد» اضغط سماح. لمزيد من استكشاف مشكلات عدم الاتصال وعدم الاستجابة للنقر راجع استكشاف أخطاء Ultrafast.
❌ الاعتقاد بأن نموذج النص لا يمكن أن يكون إلا Mercury من OpenRouter
السبب: القيمة النموذجية في .env.example هي OpenRouter + inception/mercury-2.5، فتبدو وكأنها ارتباط إجباري.
الحقيقة: يذكر README صراحةً أن Gemini و GLM و DeepSeek يمكنها جميعًا استخدام هذا الـ helper المتوافق مع OpenAI؛ وعند عدم تعيين TEXT_MODEL_BASE_URL / TEXT_MODEL في model.py، تكون القيمة الافتراضية في الكود هي DeepSeek ببساطة (https://api.deepseek.com/v1 + deepseek-chat).
الطريقة الصحيحة: بدّل نقطة النهاية واسم النموذج وفق الطريقة B / C في الخطوة 3، وقم بتهيئة reasoning وفق ذلك التنبيه ⚠️؛ وبعد التبديل شغّل demo مرة واحدة للتحقق من أن خطوة الكتابة تعمل بشكل طبيعي.
نصائح متقدمة (اختيارية)
تغيير المنفذ. عندما يكون 8766 مشغولًا، نفّذ في الصدفة قبل بدء التشغيل export TYPESAFE_DEMO_PORT=8767 (وفي Windows PowerShell استخدم $env:TYPESAFE_DEMO_PORT="8767") ثم uv run jev. ملاحظة: يجب تعيين هذا المتغيّرقبل بدء العملية — إذ يقرأ demo.py المنفذ عند استيراد الوحدة، فكتابته في .env لن يسري في الوقت المناسب.
تدرّب أولًا على صفحات fixture المحلية. الخياران Travel planner · fixture و Reading room · fixture في القائمة المنسدلة للسيناريوهات يشغّلان صفحات محلية مرفقة بالمستودع (static/fixture.html) دون الوصول إلى الإنترنت — فإذا أردت رؤية كيف يتحرك الـ agent أولًا دون لمس مواقع حقيقية بعد، فاخترهما.
لا تريد التثبيت محليًا؟ استخدم الخدمة السحابية. يوفر Browser Use Cloud نسخة مستضافة من BU Ultrafast، والموقع الرسمي يوضح أنها متاحة لجميع الخطط: يكفي تهيئة model: "bu-ultrafast" (cloud.browser-use.com). النسخة مفتوحة المصدر تعمل على حاسوبك، أما الخدمة السحابية فتعمل على Browser Use Cloud.
خلاصة الدرس
✅ تثبيت jev-ultrafast = git clone ← uv sync ← cp .env.example .env ← uv run jev، أربع مراحل وخمسة أوامر، مأخوذة حرفيًا من قسم «Try it» في README وقابلة للاستخدام كما هي.
✅ لكل مفتاح من المفتاحين مجاله: TYPESAFE_API_KEY يخوّل قرارات Jev (تُستخدم في كل دورة)، و TEXT_MODEL_API_KEY يخوّل الـ LLM الصغير المستخدم عند الكتابة (وغيابه لا يُبلَّغ عنه إلا عند TYPE_TEXT، ويمكن البحث بنص رسالة الخطأ الأصلي).
✅ يثبّت uv sync التبعيات المقفلة في المستودع داخل .venv بجوار المشروع (بما فيها browser-harness 0.1.13 الخاص بالاتصال بـ Chrome)؛ و uv run يؤكد مزامنة البيئة تلقائيًا في كل مرة.
✅ يتصل Chrome عبر Browser Harness، و uv run browser-harness --doctor هو أمر التشخيص الرسمي؛ وتذكّر السماح بالتصحيح عن بُعد عند الاتصال الأول.
✅ نموذج النص غير مرتبط بـ OpenRouter: DeepSeek هو القيمة الافتراضية في الكود، و GLM / Gemini يعملان عبر نقاط النهاية المتوافقة مع OpenAI.
مراجعة حقول التهيئة الرئيسية (.env، والقيم النموذجية مأخوذة من .env.example):
| الحقل | القيمة الموصى بها | الشرح |
|---|---|---|
TYPESAFE_API_KEY | (إلزامي) | مفتاح قرارات Jev، يُحصل عليه من console.typesafe.ai/keys |
TEXT_MODEL_API_KEY | (إلزامي) | مفتاح الـ helper النصي، يتبع الخدمة المختارة |
TYPESAFE_MODEL | jev-latest | نموذج القرار، يمكن حذفه (الافتراضي هو نفسه) |
TEXT_MODEL_BASE_URL | حسب الطريقة A/B/C | نقطة نهاية نموذج النص، يمكن حذفها مع DeepSeek |
TEXT_MODEL | حسب الطريقة A/B/C | اسم نموذج النص، يمكن حذفه مع DeepSeek |
TEXT_MODEL_REASONING | none | إيقاف الاستدلال، يُنصح بإبقائه عند تغيير النموذج |
استعراض الدرس القادم
البيئة جاهزة، وفي الدرس القادم تشغيل Google Flights: إتمام بحث حقيقي في 7 ثوانٍ سيقوم الـ agent بعمل حقيقي. ستتعلم:
- تشغيل بحث Google Flights حقيقي في inspector، ومشاهدة كيف تُصرف 7 ثوانٍ بعينيك
- إعادة إنتاج التسجيل الرسمي باستخدام
examples/flights.py --keep-open: البحث، والتحقق المستقل، وحفظ trace، دون اختيار أو حجز - افهم ما الذي يتحقق منه
verify()المستقل في المثال — DONE لا يُحتسب، التحقق عبر الكود هو ما يُحتسب - ما العوامل التي تؤثر على عدد الثواني هذا (تُترك تفاصيل منهجية القياس إلىقراءة الأداء)
ملحق: مرجع الكود المصدري
انقر للتوسيع لعرض موضع الكود المصدري
وقت التحديث: 2026-11-04 (المستودع github.com/browser-use/jev-ultrafast، مصدر المعلومات المحلي sources/jev/repo-ultrafast/)
| الوظيفة | مسار الملف | المواضع الرئيسية |
|---|---|---|
| أمر التثبيت وشرح الاتصال بـ Chrome | README.md | قسم «Try it» (git clone / uv sync / cp / uv run jev / 8766 / --doctor / السماح بالتصحيح عن بُعد)؛ «Use the library» (طريقة استخدام --env-file) |
| مثال على متغيرات البيئة | .env.example | الملف بالكامل: 6 متغيرات + 1 سطر تعليق (شرح TYPE_TEXT الضروري) |
| إصدار Python والتبعيات ونقطة دخول jev | pyproject.toml | requires-python = ">=3.12"؛ dependencies (browser-harness==0.1.13، httpx[http2])؛ [project.scripts] jev = "jev_ultrafast.demo:main" |
| منفذ inspector وتحميل .env | jev_ultrafast/demo.py | L16 PORT (الافتراضي 8766، يقرأ TYPESAFE_DEMO_PORT)؛ L23 load_environment() (.env في cwd، setdefault)؛ L131 main() (يطبع Jev Ultrafast: http://127.0.0.1:8766؛ يربط فقط 127.0.0.1) |
| سيناريوهات العرض التجريبي وطول الهدف | jev_ultrafast/demo.py | L44 command() (scenario ∈ travel/research/flights؛ goal 1–2000 حرفًا) |
| استخدام المفتاحين ورسائل الخطأ | jev_ultrafast/model.py | L119 TypeSafe الطلب (Bearer TYPESAFE_API_KEY)؛ L160–168 field_text() (TEXT_MODEL_API_KEY ضروري، نقطة النهاية الافتراضية لـ DeepSeek، ثلاثة فروع لـ reasoning) |
| أزرار اللوحة والهدف المُعبأ مسبقًا | jev_ultrafast/static/index.html | قائمة السيناريوهات المنسدلة L33–36؛ الهدف الافتراضي وStart demo L40–44؛ Choose next / Execute choice / Run automatically / Pause L56–59 |
| .env لا يدخل إلى git | .gitignore | السطر 1 .env؛ كما يُتجاهل أيضًا .venv/، artifacts/ |
| تثبيت uv وسلوك sync | الوثائق الرسمية لـ uv | docs.astral.sh/uv (أوامر curl/irm في Installation؛ التعريف والسلوك الافتراضي في Locking and syncing؛ موضع .venv انظر Projects → Structure and files) |