BYOK ونشر المؤسسات

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

واجهتان: VS Code المفاتيح هي contextmint.* في الإعدادات أو settings.json على جهاز كل مطوّر — يُطبَّق معظمها عند الإرسال التالي للمحادثة دون إعادة تشغيل واجهة API. الخادم تعيش المفاتيح في config/contextmint.defaults.yaml على مضيف API، وتُتجاوَز عبر ~/.contextmint/server.defaults.yaml أو .env المضيف — أعد تشغيل واجهة API بعد التغييرات (تبويب Engine ← الخادم، أو نشر الحاوية).

1 — توجيه BYOK السحابي

يتيح إحضار المفتاح الخاص بك (BYOK) للمطوّرين توجيه توليد المحادثة إلى مزوّد نموذج لغوي خارجي (OpenAI، Anthropic، Groq) باستخدام مفاتيح API مخزَّنة في VS Code — وليس على الخادم. لا يزال الاسترجاع والفهرسة وتجميع الأدلة يعمل على مضيف API الخاص بـContextMint؛ فقط خطوة التوليد النهائية قد تُخرِج سياقاً منقَّحاً إلى المزوّد الذي اخترته.

لا يتطلب BYOK خادم مؤسسة مشتركاً أبداً. يعمل مع إعداد Engine المحلي الافتراضي http://127.0.0.1:8000.

قائمة تحقق نشر BYOK

المنصة / المشغّل — فعّل allow_cloud_dispatch على مضيف API (إن كنت تتحكم فيه).
كل مطوّر — عيّن contextmint.cloudEnabled إلى true.
كل مطوّر — شغّل ContextMint: Configure Cloud API Key وخزّن مفتاح مزوّد.
كل مطوّر — اختر Cloud أو Auto في منتقي نموذج الإنشاء وأرسل رسالة اختبار.
تحقّق — تُظهر شارة التوجيه cloud؛ ويسرد المفتش الطبقة السحابية. إذا بقيت محلية، انظر استكشاف الأخطاء وإصلاحها ← السحابة.

إعدادات VS Code (كل مطوّر)

عدّل عبر Ctrl+, (ابحث عن contextmint) أو settings.json الخاص بالمستخدم/مساحة العمل.

contextmint.cloudEnabled منطقي · الافتراضي false

ما تفعله. تفعيل رئيسي لتوجيه النموذج اللغوي السحابي من الإضافة. عند true، قد تعيّن الإضافة prefer_cloud في طلبات المحادثة إذا وُجد مفتاح مزوّد وسمح منتقي النموذج بالسحابة. عند false، يبقى كل التوليد على Ollama المحلي بغض النظر عن المفاتيح.

متى تفعّله. عندما يوافق فريق الأمان لديك على الاستدلال الخارجي لتوليد المحادثة ولديك مفتاح API لمزوّد.

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

كيفية التغيير.

افتح VS Code ← الإعدادات ← ابحث عن cloud enabled.
فعّل ContextMint: Enable Cloud LLM Provider Routing، أو أضف إلى settings.json:
```
"contextmint.cloudEnabled": true
```
أرسل رسالة محادثة جديدة — لا حاجة لإعادة تشغيل الخادم.

الأمر: ContextMint: Configure Cloud API Key أمر VS Code · ليس مفتاحاً في settings.json

ما يفعله. يخزّن مفاتيح API للمزوّدين في SecretStorage الخاص بـVS Code (سلسلة مفاتيح نظام التشغيل المشفَّرة). المزوّدون المدعومون: OpenAI، Anthropic، Groq. تقرأ الإضافة المفاتيح وقت الإرسال — لا تُكتَب أبداً في إعداد Engine أو YAML الخادم أو سجلات الخادم.

متى تشغّله. بعد تفعيل contextmint.cloudEnabled وقبل اختيار Cloud / Auto في منتقي النموذج.

كيفية التغيير.

Ctrl+Shift+P ← ContextMint: Configure Cloud API Key (Preview).
اختر المزوّد ← ألصق المفتاح ← أكّد.
لتدوير مفتاح أو إزالته، شغّل الأمر مجدداً واستبدل القيمة أو امسح المطالبة.

تحقّق: يجب أن يعرض منتقي نموذج الإنشاء خيارات الطبقة السحابية؛ ولا ينبغي أن يطالب إرسال اختباري باختيار Cloud بمفتاح مفقود.

منتقي نموذج الإنشاء — Local / Auto / Cloud واجهة مستخدم · لكل رسالة · ليس مفتاحاً في settings.json

ما يفعله. يتحكم بالتوجيه لهذا الإرسال فقط (يُتذكَّر الاختيار في مساحة العمل حتى تغيّره). يجب أن يكون BYOK مفعَّلاً بالفعل (contextmint.cloudEnabled + مفتاح مخزَّن واحد على الأقل + allow_cloud_dispatch على الخادم) قبل أن يحدث التسليم السحابي.

المنتقي	لهذه الرسالة
Local	يعمل دائماً على Ollama المحلي — حتى لو كان BYOK مفعَّلاً والمفاتيح موجودة. استخدمه عندما يجب ألا تخرج هذه الإجابة.
Auto	يختار الخادم الطبقة من نية الاستعلام (بحث الرمز ← محلي؛ الشرح ← سحابة متوسطة؛ التوليد ← سحابة متميزة). يحدث التسليم السحابي فقط عندما تنجح بوابات BYOK و تطابق النية طبقة سحابية.
Cloud	الاستخدام الأساسي: رسائل الصور — يتيح الرؤية السحابية عندما تختار أيضاً نموذج رؤية سحابياً. بالنسبة إلى النص، استخدم Auto لترك النية تختار طبقة سحابية؛ وLocal لضمان Ollama.

كيفية التغيير. شريط إنشاء المحادثة ← القائمة المنسدلة للنموذج ← اختر Local أو Auto أو Cloud ← أرسل. تُظهر شارة التوجيه على الإجابة الطبقة المحلية أو السحابية المستخدَمة.

إذا فشلت السحابة (حد المعدل، انقطاع، مفتاح مفقود)، يمكن للإضافة الرجوع إلى Ollama المحلي لتلك الرسالة. انظر استكشاف الأخطاء وإصلاحها ← السحابة.

مفاتيح مزوّدين متعددة (OpenAI + Anthropic + Groq) SecretStorage في VS Code · مفتاح واحد لكل مزوّد

ما يفعله. يمكنك تخزين حتى ثلاثة مفاتيح — واحد لكل من openai وanthropic وgroq. تعيش في فتحات SecretStorage منفصلة (contextmint.apiKey.openai، إلخ). لا تُدمَج المفاتيح أو تُرسَل إلى خادم Python أبداً.

أي مفتاح يُستخدَم. أنت لا تختار المزوّد لكل رسالة في الإعدادات. يسمّي قرار توجيه الخادم نموذجاً (مثل claude-3-5-sonnet ← Anthropic، groq/llama3-70b ← Groq، gpt-4o ← OpenAI)؛ تربط الإضافة ذلك النموذج بالمفتاح المخزَّن المطابق وقت cloud_dispatch. إذا لم يكن للمزوّد الموجَّه إليه مفتاح، يطالب VS Code مرة واحدة عبر تدفق Configure Cloud API Key.

كيفية إضافة المفاتيح أو تدويرها.

Ctrl+Shift+P ← ContextMint: Configure Cloud API Key (Preview).
اختر بسرعة openai أو anthropic أو groq.
ألصق المفتاح ← كرّر لكل مزوّد تحتاجه.
شغّل مجدداً بقيمة جديدة للتدوير؛ تتم إزالته عبر نفس المطالبة (الإلغاء = بدون تغيير).

نصيحة: خزّن فقط المزوّدين الذين توافق عليهم مؤسستك. مع منتقي Auto، قد يُوجَّه سؤال «اشرح هذه العمارة» إلى Anthropic (طبقة متوسطة) بينما قد يُوجَّه توليد الكود إلى طبقة متميزة — يستخدم كل منهما مفتاحه الخاص إن كان مهيَّأً.

contextmint.chat.cloudThinkingEnabled منطقي · الافتراضي true

ما يفعله. عند استخدام نماذج الاستدلال الخاصة بك من Anthropic أو OpenAI، يطلب ويبثّ «تفكير» / استدلالاً ممتداً على مستوى النموذج من المزوّد.

متى تعطّله. سير عمل حساس لزمن الاستجابة أو مزوّدون لا يدعمون بثوث التفكير.

كيفية التغيير. الإعدادات ← ابحث عن cloud thinking، أو:

"contextmint.chat.cloudThinkingEnabled": false

ميزانيات ذات صلة: contextmint.chat.cloudThinkingBudgetTokens (الافتراضي 10000) وcontextmint.chat.cloudThinkingBudgetMinTokens (الافتراضي 1024) — عدّل في الإعدادات إذا اقتُطع التفكير الممتد لـClaude.

إعدادات الخادم (مشغّل مضيف API)

مطلوب على الجهاز الذي يشغّل واجهة API الخاصة بـContextMint — Engine محلي (127.0.0.1:8000) أو مضيف فريق مشترك. عدّل في Engine ← إعداد الخادم، أو ملف التجاوز، أو .env؛ ثم أعد تشغيل واجهة API.

allow_cloud_dispatch خادم · منطقي · الافتراضي false

ما يفعله. بوابة على جانب الخادم لأحداث SSE الخاصة بـcloud_dispatch. عند false، تتجاهل واجهة API قيمة prefer_cloud من الإضافة وتشغّل Ollama المحلي دائماً — حتى لو فعّل المطوّر cloudEnabled وأعدّ المفاتيح.

متى تفعّله. عندما تسمح سياسة المنصة بالتسليم السحابي وتشغّل تثبيتاً مدفوعاً أو معتمَداً (وليس تجريبياً / سيادياً افتراضياً).

كيفية التغيير.

الخيار أ — تجاوز YAML — أضف إلى ~/.contextmint/server.defaults.yaml على مضيف API:
```
allow_cloud_dispatch: true
```
الخيار ب — متغيّر بيئة — في .env الخادم أو مواصفة الحاوية:
```
ALLOW_CLOUD_DISPATCH=true
```
أعد تشغيل واجهة API (Engine ← الخادم ← إعادة تشغيل، أو أعد نشر الحاوية).
أعد الاختبار: الإضافة مع cloudEnabled + مفتاح ← نموذج سحابي ← يجب أن تُظهر الشارة الطبقة السحابية.

chat.image_cloud_opt_in_only خادم · منطقي · الافتراضي true

ما يفعله. عند true، لا تُرسَل مرفقات الصور بصمت إلى الرؤية السحابية — يجب على المستخدم اختيار نموذج رؤية سحابي صراحةً في الإنشاء. يحافظ على الافتراضي السيادي للقطات الشاشة ومقتطفات واجهة المستخدم.

كيفية التغيير. في تجاوز الخادم ضمن قسم chat::

chat:
  image_cloud_opt_in_only: true

أو متغيّر بيئة: CHAT__IMAGE_CLOUD_OPT_IN_ONLY=true. أعد تشغيل واجهة API.

chat.image_prefer_cloud_when_both خادم · منطقي · الافتراضي false

ما يفعله. عندما تتوفر الرؤية المحلية والسحابية معاً واختار المستخدم السحابة، يتحكم فيما إذا كانت السحابة مفضَّلة على رؤية Ollama المحلية. الافتراضي false يبقي الرؤية المحلية أساسية.

متى تفعّله. عندما يكون معيار المؤسسة رؤية سحابية فقط وتكون رؤية Ollama المحلية احتياطية فقط.

كيفية التغيير. تجاوز الخادم:

chat:
  image_prefer_cloud_when_both: false

أعد تشغيل واجهة API. التفاصيل: أدلة الصور وARGUS.

تذكير بتدفق البيانات: يرسل BYOK سياقاً مجمَّعاً منقَّحاً إلى المزوّد الذي اخترته من جهاز المطوّر. لا تلمس مفاتيح API الخادم أبداً. تسجّل شارة التوجيه والمفتش الطبقة السحابية للتدقيق.

2 — خادم API مؤسسي مشترك

يوجّه وضع الخادم المؤسسي المطوّرين إلى مكدس API مشترك لـContextMint (Docker / Helm على بنيتك التحتية) بدلاً من تشغيل كل حاسوب محمول لـEngine. يهيّئ المطوّرون VS Code لاستدعاء عنوان URL الخاص بالفريق والمصادقة عبر OIDC. هذا منفصل عن BYOK — يمكنك تشغيل المؤسسة محلياً فقط (بدون خروج سحابي) أو إضافة BYOK لاحقاً عبر القسم 1.

مواءمة المسار مطلوبة. يفهرس الخادم مسارات نظام الملفات التي يمكنه قراءتها. لا يمكن لحاسوب محمول مع نسخة مستنسخة في C:\dev\repo استخدام serverUrl بعيد ما لم ير الخادم نفس المسار (Remote SSH، أو تركيب مشترك، أو مستودع مستنسخ على الخادم). انظر الثقة ← نماذج النشر.

قائمة تحقق نشر المؤسسة

فريق المنصة — انشر API + استدلالاً متوافقاً مع OpenAI (غالباً vLLM) + Chroma (+ Redis إن استُخدم) على البنية التحتية الداخلية. انظر نشر الخادم السيادي.
فريق المنصة — فعّل auth.enabled، واضبط auth.mode على oidc، وهيّئ المُصدِر/الجمهور، واضبط AUTH__JWT_SECRET في .env المضيف.
فريق المنصة — واءم مسارات المستودع (استنساخ على الخادم، تركيب NFS، أو Remote SSH).
كل مطوّر — عيّن contextmint.serverUrl إلى عنوان URL الأساسي HTTPS للفريق.
كل مطوّر — عيّن contextmint.enterpriseMode إلى true وcontextmint.oidcProviderId إلى مزوّد الهوية الخاص بكم.
كل مطوّر — سجّل الدخول عبر مصادقة VS Code عند المطالبة؛ تأكد أن شريط الحالة يُظهر الاتصال بخادم الفريق.

إعدادات الخادم (فريق المنصة)

على مضيف API: Engine ← إعداد الخادم، أو ~/.contextmint/server.defaults.yaml، أو .env. تذهب الأسرار إلى .env فقط — لا تودعها أبداً في YAML على git.

auth.enabled خادم · منطقي · الافتراضي false

ما يفعله. يتطلب JWT من نوع Bearer صالحاً على مسارات /api/v1/* المحمية. معطَّل للتثبيتات المحلية أحادية المستخدم؛ مفعَّل لخوادم الفرق المشتركة.

كيفية التغيير.

تجاوز الخادم:
```
auth:
  enabled: true
```
أو متغيّر بيئة: AUTH__ENABLED=true
عيّن سر JWT (أدناه) قبل التفعيل في الإنتاج.
أعد تشغيل واجهة API.

auth.mode خادم · نص · الافتراضي local

ما يفعله. local = بدون تحقق من المصادقة. oidc = تحقق من مُصدِر وجمهور وتوقيع JWT في الطلبات الواردة من الإضافة.

كيفية التغيير. تجاوز الخادم:

auth:
  mode: oidc

أو متغيّر بيئة: AUTH__MODE=oidc. أعد تشغيل واجهة API.

auth.oidc_issuer و auth.oidc_audience خادم · نصوص · اختياري

ما تفعله. عند ضبطها، ترفض واجهة API الرموز التي لا تطابق مطالبات iss أو aud — ما يربط رموز Bearer للإضافة بمزوّد الهوية لديكم (Microsoft Entra ID، Okta، Keycloak، إلخ).

كيفية التغيير. تجاوز الخادم (مثال لـEntra ID):

auth:
  oidc_issuer: "https://login.microsoftonline.com/{tenant-id}/v2.0"
  oidc_audience: "{application-client-id}"

أو متغيّرات بيئة: AUTH__OIDC_ISSUER=... وAUTH__OIDC_AUDIENCE=.... أعد تشغيل واجهة API.

احصل على المُصدِر والجمهور من تسجيل تطبيق مزوّد الهوية لديكم. يجب أن يطابقا الرموز التي يمرّرها VS Code عند تفعيل enterpriseMode.

AUTH__JWT_SECRET (متغيّر بيئة) خادم · سر · ليس في YAML

ما يفعله. سر HMAC للتحقق من JWT بخوارزمية HS256 (auth.jwt_algorithm). مطلوب عندما يكون auth.enabled صحيحاً. يُطابق auth.jwt_secret في إعداد الخادم.

كيفية التغيير.

ولّد سلسلة عشوائية قوية (32 بايت أو أكثر).
أضفها إلى .env مضيف API (أو مخزن أسرار الحاوية):
```
AUTH__JWT_SECRET=your-long-random-secret-here
```
لا تودعها أبداً في git أو تلصقها في server.defaults.yaml.
أعد تشغيل واجهة API بعد التدوير؛ يعيد المطوّرون المصادقة في VS Code.

auth.require_workspace_acl و auth.sso_default_role خادم · منطقي + نص

ما تفعله. يفرض require_workspace_acl أدواراً لكل مساحة عمل (viewer، dev، admin) على مسارات الاستعلام. يُمنَح sso_default_role (الافتراضي viewer) عند أول تسجيل دخول SSO حين لا يوجد دور صريح.

كيفية التغيير. تجاوز الخادم:

auth:
  require_workspace_acl: true
  sso_default_role: viewer

أعد تشغيل واجهة API. أدر أدوار مساحة العمل عبر أدوات ACL أو واجهة API الإدارية لديك.

allowed_workspace_roots خادم · قائمة · الافتراضي فارغة (يسمح بأي شيء)

ما يفعله. عندما لا يكون فارغاً، يرفض تسجيل مساحات العمل للمسارات خارج الدلائل المدرَجة — مفيد لحصر الفهرسة في نقاط تركيب معتمَدة.

كيفية التغيير. تجاوز الخادم:

allowed_workspace_roots:
  - /data/repos
  - /mnt/shared-engineering

أو متغيّر بيئة: ALLOWED_WORKSPACE_ROOTS=/data/repos,/mnt/shared-engineering. أعد تشغيل واجهة API.

إعدادات VS Code (كل مطوّر)

لكل جهاز — واجهة الإعدادات أو settings.json. بدون إعادة تشغيل الخادم.

contextmint.serverUrl نص · الافتراضي http://127.0.0.1:8000

ما يفعله. عنوان URL الأساسي لكل استدعاءات API الخاصة بـContextMint (الصحة، الفهرسة، المحادثة). الافتراضي محلي الأولوية هو الاتصال الداخلي؛ يوجّه وضع المؤسسة إلى مضيف فريقكم.

كيفية التغيير.

الإعدادات ← ابحث عن server url، أو:

"contextmint.serverUrl": "https://contextmint.corp.example"

استخدم اسم مضيف داخلي HTTPS؛ أضف المنفذ فقط إذا لم يكن 443.
أعد تحميل النافذة أو انتظر فحص الصحة التالي — يجب أن يُظهر شريط الحالة اتصالاً بخادم الفريق.

محلي الأولوية: اترك الافتراضي http://127.0.0.1:8000 عند استخدام Engine على نفس الجهاز.

contextmint.enterpriseMode منطقي · الافتراضي false

ما يفعله. يحوّل الإضافة إلى اتصال مؤسسي: يمرّر تسجيل دخول OIDC في VS Code رمز Bearer مع كل طلب API. إذا تعذّر الوصول إلى خادم الفريق، يرجع إلى contextmint.localFallbackUrl (إن كان مهيَّأً).

متى تفعّله. عندما يشير contextmint.serverUrl إلى خادم مشترك مع auth.enabled: true.

متى تعطّله. Engine محلي الأولوية على الاتصال الداخلي، أو شبكة VLAN مختبرية بدون SSO، أو حواسيب محمولة على طراز Hub71 «الإضافة فقط» تتصل بمضيف GPU للفريق بدون JWT.

كيفية التغيير.

"contextmint.enterpriseMode": true

يطالب VS Code بتسجيل الدخول عبر oidcProviderId عند استدعاء API التالي.

contextmint.oidcProviderId نص · الافتراضي فارغ

ما يفعله. يخبر VS Code بمزوّد المصادقة المدمج الذي يجب استخدامه لـSSO عندما يكون enterpriseMode مفعَّلاً — مثل microsoft أو github أو معرّف مزوّد مخصَّص من إضافة مصادقة VS Code لديكم.

كيفية التغيير.

"contextmint.oidcProviderId": "microsoft"

ينطبق فقط عندما يكون enterpriseMode مساوياً true. سجّل الخروج ثم الدخول مجدداً بعد تغيير المزوّد.

contextmint.localFallbackUrl نص · الافتراضي http://127.0.0.1:8000

ما يفعله. عندما يكون enterpriseMode مفعَّلاً ويكون serverUrl الخاص بالفريق معطَّلاً، تعيد الإضافة المحاولة مقابل عنوان URL الاتصال الداخلي هذا لـEngine حتى يستمر المطوّرون بالعمل دون اتصال.

متى تضبطه. عندما يشغّل المطوّرون أيضاً Engine محلياً كاحتياط طارئ.

كيفية التغيير.

"contextmint.localFallbackUrl": "http://127.0.0.1:8000"

يُتجاهَل عندما يكون enterpriseMode مساوياً false.

contextmint.localJwtSecret نص · الافتراضي فارغ

ما يفعله. سر HS256 اختياري لرموز JWT الموقَّعة تلقائياً على المضيف المحلي عند اختبار المصادقة مقابل Engine محلي. عند تركه فارغاً، تقرأ الإضافة AUTH__JWT_SECRET من ملف .env الخاص بمساحة العمل.

متى تستخدمه. للتطوير المحلي فقط — لمطابقة واجهة API محلية مع auth.enabled بدون OIDC كامل. يُفضَّل OIDC + enterpriseMode لخوادم الفرق الحقيقية.

كيفية التغيير. الإعدادات ← ابحث عن local jwt، أو اضبطه في settings.json. لا تودع الأسرار في git الخاص بمساحة العمل.

الجمع بين الخادم المؤسسي وBYOK

يتراكب هذان المساران: وجّه contextmint.serverUrl إلى مضيف الفريق و فعّل مفاتيح BYOK على الحاسوب المحمول للتوليد السحابي. يجب على فريق المنصة تفعيل allow_cloud_dispatch على مضيف API المشترك؛ ولا يزال على كل مطوّر تعيين contextmint.cloudEnabled وإعداد المفاتيح محلياً. مصادقة المؤسسة وخروج BYOK ضوابط مستقلة.

مواد المراجعة الأمنية

يتلقى شركاء التصميم ملخصات العمارة، ومخططات تدفق البيانات، ودعم الاستبيانات. تواصل عبر anis@contextmint.ai أو التقدّم كشريك تصميم.

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