BroadRouter

استخدام Spring AI مع BroadNet Inference (OpenAI base-url)

آخر تحديث

أضف spring-ai-starter-model-openai، ثم اضبط spring.ai.openai.base-url على https://inference.broadnet.ai/v1، وspring.ai.openai.api-key على مفتاح BroadNet، وspring.ai.openai.chat.model على معرّف من BroadNet مثل broadnet/glm-5.3. واضبط spring.ai.openai.chat.max-tokens مع ترك مساحة للاستدلال. يستخدم Spring AI 2.x حزمة openai-java SDK، التي تُلحق /chat/completions بالرابط الأساسي.

Spring AI هو إطار عمل مشروع Spring للذكاء الاصطناعي في Java. ويقرأ OpenAI chat starter فيه قيمة base-url، فيمكنه استدعاء أي خادم متوافق مع OpenAI. وتقدّم BroadNet Inference واجهة chat completions القياسية على https://inference.broadnet.ai/v1. BroadRouter هو موقع BroadNet نفسها؛ ويتبع هذا الدليل مرجع Spring AI 2.0.2.

أضف الـ starter

بعد إعداد Spring AI BOM (راجع توثيق إدارة الاعتماديات في Spring AI):

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

الإعداد

الملف application.properties:

spring.ai.openai.base-url=https://inference.broadnet.ai/v1
spring.ai.openai.api-key=${BROADNET_API_KEY}
spring.ai.openai.chat.model=broadnet/glm-5.3
spring.ai.openai.chat.max-tokens=2000
export BROADNET_API_KEY='your-broadnet-key'

أبقِ /v1 في الرابط. ففي Spring AI 2.x تذهب القيمة إلى عميل openai-java دون تغيير (إذ تعيدها OpenAiSetup.calculateBaseUrl كما هي)، وذلك العميل يضيف /chat/completions. والقيمة الافتراضية التي تستبدلها هي https://api.openai.com/v1.

الاستدعاء والاختبار

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;

@Bean
CommandLineRunner smokeTest(ChatClient.Builder builder) {
    return args -> {
        ChatClient chat = builder.build();
        System.out.println(chat.prompt().user("Say hello in five words.").call().content());
    };
}

شغّل التطبيق. فإن طُبعت إجابة، فالمفتاح والرابط ومعرّف النموذج صحيحة.

إعدادات مهمة مع BroadNet

  • max-tokens لا max-completion-tokens. يقول توثيق Spring AI إنهما لا يجتمعان وإن ضبطهما معًا خطأ. ويصف المرجع التقني لـ BroadNet API الحقل max_tokens. وتستدل نماذج DeepSeek V4.1 Flash وGLM 5.3 وQwen3.8 27B أولًا، ويُحتسب الاستدلال ضمن الحد.
  • نص الاستدلال. يستطيع Spring AI عرض reasoning_content من الخوادم المتوافقة مع OpenAI التي تعيده. ويُبلغ المرجع التقني لـ BroadNet API عن أعداد رموز الاستدلال في usage، لكنه لا يَعِد بإعادة نص الاستدلال نفسه، فلا تعتمد عليه.
  • تجاوز خاص بالمحادثة. تتقدّم spring.ai.openai.chat.base-url وspring.ai.openai.chat.api-key على الخصائص المشتركة لنموذج المحادثة. استخدمهما إن كان على نماذج Spring AI الأخرى من OpenAI (مثل التضمينات) أن تبقى على OpenAI.
  • إعادة المحاولة. القيمة الافتراضية لـ spring.ai.retry.max-attempts هي 10 مع تراجع أُسّي (exponential backoff). وعلى مفتاح الدفع حسب الاستخدام قد يستنزف ذلك الحد الدقيقي سريعًا؛ ففكّر في خفضها.

أي نموذج تختار

الاستخدام spring.ai.openai.chat.model
استدعاء الأدوات والمخرجات المنظَّمة broadnet/glm-5.3
الصور أو النص العربي broadnet/qwen3.8-27b
المستندات الطويلة، خطة بسعر ثابت broadnet/deepseek-v4.1-flash
الرصيد المبدئي المجاني broadnet/gemma-4-26b-a4b

أسعار كل النماذج.

حل المشكلات

  • 401. المفتاح خاطئ أو منتهي الصلاحية أو استنفد رصيده، أو أن BROADNET_API_KEY غير مضبوط لـ JVM.
  • 404. الرابط الأساسي ينقصه /v1، أو أن معرّف النموذج خاطئ. النماذج المدفوعة تحتاج إلى شحن الرصيد؛ والرصيد البالغ $5 يغطي broadnet/gemma-4-26b-a4b ونموذجَي Transcribe.
  • content() فارغ. استهلك الاستدلال ميزانية المخرجات. ارفع max-tokens. راجع لماذا تعود الإجابات فارغة.
  • 400 مع ضبط حدَّي الرموز كليهما. احذف max-completion-tokens.
  • 429. يسمح مفتاح الدفع حسب الاستخدام بـ 30 من الطلبات في الدقيقة و4 قيد التنفيذ. راجع الأخطاء وإعادة المحاولة.

أسئلة شائعة

هل يجب أن تتضمن قيمة spring.ai.openai.base-url المسار /v1؟

نعم. ففي Spring AI 2.x تُمرَّر القيمة كما هي إلى عميل openai-java، وقيمته الافتراضية هي https://api.openai.com/v1. استخدم https://inference.broadnet.ai/v1.

هل أستخدم max-tokens أم max-completion-tokens مع BroadNet؟

استخدم max-tokens. يقول توثيق Spring AI إن الخيارين لا يجتمعان. ويصف المرجع التقني لـ BroadNet API الحقل max_tokens، والاستدلال يُحتسب ضمنه، فاسمح بـ 1,000 رمز أو أكثر.

هل يعمل استدعاء الأدوات في Spring AI مع BroadNet؟

استخدم GLM 5.3 أو Qwen3.8 27B، فهما مُدرجان مع الأدوات لدى BroadNet. ولا يُدرج توثيق BroadNet استدعاء الأدوات لنموذج DeepSeek V4.1 Flash.

هل يمكنني إبقاء OpenAI للتضمينات واستخدام BroadNet للمحادثة؟

نعم. فالخاصيتان spring.ai.openai.chat.base-url وspring.ai.openai.chat.api-key تتقدّمان على الخصائص المشتركة لنموذج المحادثة وحده. ولا يُدرج المرجع التقني لـ BroadNet API نقطة نهاية للتضمينات (embeddings).

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity