آموزش حل ارور Failed to initialize OpenAI client و pydantic_core در هرمس ایجنت (رفع با یک دستور تکu200cخطی)

اگر از هرمس ایجنت (Hermes Agent) یا پنل وب آن استفاده می‌کنید و ناگهان هنگام اجرای نشست یا چت با ارور عجیب Failed to initialize OpenAI client: No module named 'pydantic_core._pydantic_core' روبرو شده‌اید، این راهنما دقیقاً برای شماست. در این مقاله هم یک دستور تک‌خطی جادویی برای حل خودکار مشکل در چند ثانیه آماده کرده‌ایم و هم ریشه ماجرا را به زبان بسیار ساده کالبدشکافی می‌کنیم.

Error: Failed to initialize OpenAI client: No module named 'pydantic_core._pydantic_core'
Provider details: Failed to initialize OpenAI client: No module named 'pydantic_core._pydantic_core' http://127.0.0.1:8787/session/...

curl -sSL https://mrhermes.ir/fix-pydantic.sh | bash

python3 -c "import sys, pathlib; p=pathlib.Path.home()/'.hermes/hermes-agent/pm/environments.py'; c=p.read_text('utf-8'); g='            env_version = venv_python_version(environment)n            if env_version is not None and (sys.version_info.major, sys.version_info.minor) != env_version:n                return _require_own_dependencies(project_root)n'; g2='        env_version = venv_python_version(environment)n        if env_version is not None and (sys.version_info.major, sys.version_info.minor) != env_version:n            return _require_own_dependencies(project_root)n'; t1='            if environment is None:n                return _require_own_dependencies(project_root)'; t2='        if environment is None:n            return _require_own_dependencies(project_root)'; c=c.replace(t1, t1+'n'+g, 1).replace(t2, t2+'n'+g2, 1); p.write_text(c, 'utf-8'); print('[+] مشکل با موفقیت برطرف شد!')" && (launchctl kickstart -k gui/$(id -u)/ai.hermes.webui 2>/dev/null || systemctl --user restart hermes-webui 2>/dev/null || true)

۱. به زبان ساده: در پس این خطا چه اتفاقی افتاده است؟

خیلی از کاربران وقتی این خطا را می‌بینند، بلافاصله دستور pip install pydantic یا pip install openai را اجرا می‌کنند، اما با تعجب می‌بینند که ارور هنوز پابرجاست! علت چیست؟

یک کارگاه نجاری را تصور کنید که در آن دو استادکار مشغول کارند. استاد اول با ابزارهای میلی‌متری کار می‌کند و استاد دوم با ابزارهای اینچی. اگر جعبه ابزار استاد اول را اشتباهاً روی میز استاد دوم بگذارید، با اینکه آچار و پیچ وجود دارد، اما هیچ مهره‌ای بسته نمی‌شود چون ساختارشان با هم سازگار نیست!

در سیستم هرمس دقیقاً همین تداخل رخ داده است:

• محیط اول (هسته هرمس): در آپدیت‌های جدید، هرمس به آخرین نگارش یعنی پایتون ۳.۱۴ ارتقا پیدا کرده و ماژول‌های پرسرعت مانند pydantic_core با فرمت کامپایل‌شده پایتون ۳.۱۴ ذخیره شده‌اند.
• محیط دوم (وب‌سرور هرمس): سرویس پس‌زمینه پنل وب هنوز روی پایتون ۳.۱۱ بالا آمده است.
• برخورد دو دنیا: تابع راه‌انداز هرمس به اشتباه آدرس بسته‌های پایتون ۳.۱۴ را به اول مسیرهای پایتون ۳.۱۱ اضافه می‌کرد. وقتی پایتون ۳.۱۱ تلاش می‌کرد ماژول را بخواند، متوجه تفاوت ساختار باینری می‌شد و آن را نادیده می‌گرفت و پیام می‌داد که چنین فایلی اصلاً وجود ندارد!

۲. چرا دستور بالا مشکل را برای همیشه حل می‌کند؟

کد اصلاحی مستر هرمس یک «نگهبان نسخه» (Version Guard) به فایل مدیریت محیط هرمس اضافه می‌کند. با اضافه شدن این نگهبان، هرمس قبل از اتصال هر پکیج بررسی می‌کند:

«آیا نسخه پایتونی که الان در حال اجراست با نسخه پایتون این پکیج کامپایل‌شده برابر است؟ اگر برابر نیست، به بسته‌های اصلی خودِ پردازه دست نزن و اجازه بده از پکیج‌های سازگار خودش استفاده کند.»

با این منطق ساده و هوشمندانه، تداخل نسخه‌ها به طور ریشه‌ای و دائمی مسدود می‌شود.

۳. آموزش گام‌به‌گام و دستی (برای توسعه‌دهندگان)

اگر تمایل دارید خودتان فایل‌ها را ویرایش کنید و تغییرات را در قالب کد مشاهده نمایید، مراحل زیر را طی کنید:

گام اول: باز کردن فایل مدیریت محیط‌ها

فایل زیر را در ویرایشگر مورد نظر خود باز کنید:

~/.hermes/hermes-agent/pm/environments.py

گام دوم: اعمال تغییرات کد (Git Diff)

تابع activate_dependencies را پیدا کنید (حدود سطر ۳۸۰) و شرط تطابق نسخه پایتون را مطابق قطعه کد زیر اضافه کنید:

--- a/pm/environments.py
+++ b/pm/environments.py
@@ -397,6 +397,9 @@ def activate_dependencies(project_root: Path) -> None:
             environment = committed_venv(project_root)
             if environment is None:
                 return _require_own_dependencies(project_root)
+            env_version = venv_python_version(environment)
+            if env_version is not None and (sys.version_info.major, sys.version_info.minor) != env_version:
+                return _require_own_dependencies(project_root)
             release = lease_generation(environment)
             while not held and (current := committed_venv(project_root)) not in (None, environment):
                 release()
@@ -412,6 +415,9 @@ def activate_dependencies(project_root: Path) -> None:
         environment = payload_venv(project_root)
         if environment is None:
             return _require_own_dependencies(project_root)
+        env_version = venv_python_version(environment)
+        if env_version is not None and (sys.version_info.major, sys.version_info.minor) != env_version:
+            return _require_own_dependencies(project_root)
         selected = site_packages(environment)
         if not selected.is_dir():
             return

گام سوم: راه‌اندازی مجدد وب‌سرور هرمس

پس از ذخیره فایل، بسته به سیستم‌عامل خود دستور مربوطه را برای ری‌استارت وب‌سرور اجرا کنید:

در سیستم‌عامل مک (macOS):

launchctl kickstart -k gui/$(id -u)/ai.hermes.webui

در سرور لینوکس (Linux):

systemctl --user restart hermes-webui || sudo systemctl restart hermes-webui

۴. تست صحت کارکرد و اطمینان از رفع باگ

برای اینکه مطمئن شوید وب‌سرور سالم است، دستور زیر را اجرا کنید:

curl -s http://127.0.0.1:8787/health

پاسخ دریافتی باید وضعیت سالم را تایید کند:

{
  "status": "ok",
  "sessions": 0,
  "active_streams": 0
}

همچنین برای اطمینان از بارگذاری کامل کلاینت OpenAI و ماژول pydantic در پایتون ۳.۱۱، این دستور را در ترمینال بزنید:

~/.hermes/hermes-agent/venv/bin/python -c "from pydantic_core import _pydantic_core; import openai; print('All modules loaded successfully!')"

جمع‌بندی و نکات کلیدی

خطاهایی مانند No module named 'pydantic_core._pydantic_core' در پروژه‌های مدرن پایتون معمولاً به دلیل گم شدن فایل نیست، بلکه ناشی از تفاوت معماری کامپایل (ABI Mismatch) در ماژول‌های توسعه‌یافته با C یا Rust است. با اعمال نگهبان نسخه در هرمس ایجنت، محیط‌ها کاملاً عایق‌بندی شده و پایداری کلاینت OpenAI برای همیشه تضمین می‌گردد.