GPT-6.2 Astra & Sol are now live on CometAPI →

مدونة Hy4 Flash

Hy4 Flash: ما هو وكيفية استخدامه؟
Nov 18, 2026
Hy4 Flash

Hy4 Flash: ما هو وكيفية استخدامه؟

فيما يلي أمثلة عملية لاستخدام نموذج hy4-flash عبر CometAPI بلغة Python لسيناريوهات النص، البث، الصور، استخراج JSON، واستدعاء الأدوات، مع معالجة أخطاء ونصائح فوترة. نفترض وجود مفتاح API وقاعدة عنوان لخدمة CometAPI. حدّث المتغيرات حسب بيئتك. إعداد أساسي مشترك - المتغيرات البيئية: - COMET_API_KEY: مفتاح API - COMET_BASE_URL: مثال: https://api.comet.example/v1 - سنستخدم requests، مع تفعيل مهلة، ومعاودة المحاولة البسيطة. Python: import os import time import json import base64 import requests from typing import Dict, Any, Optional BASE_URL = os.getenv("COMET_BASE_URL", "https://api.comet.example/v1") API_KEY = os.getenv("COMET_API_KEY") if not API_KEY: raise RuntimeError("الرجاء ضبط المتغير البيئي COMET_API_KEY.") HEADERS = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # دالة مساعدة لإرسال POST مع معاودة محاولة تلقائية على 429/5xx def post_json(path: str, payload: Dict[str, Any], timeout: float = 30.0, max_retries: int = 3) -> requests.Response: url = f"{BASE_URL}{path}" backoff = 1.0 for attempt in range(1, max_retries + 1): try: resp = requests.post(url, headers=HEADERS, json=payload, timeout=timeout) if resp.status_code in (429, 500, 502, 503, 504): if attempt = max_retries: raise time.sleep(backoff) backoff *= 2 return resp # سيُعاد في الغالب قبل هذا السطر def raise_for_api_error(resp: requests.Response): if resp.status_code >= 400: try: err = resp.json().get("error", {}) code = err.get("code") msg = err.get("message") or err.get("error") or resp.text except Exception: code = None msg = resp.text raise RuntimeError(f"API error {resp.status_code} ({code}): {msg}") def print_usage_if_any(resp_json: Dict[str, Any]): usage = resp_json.get("usage") if usage: prompt_t = usage.get("prompt_tokens") comp_t = usage.get("completion_tokens") total_t = usage.get("total_tokens") print(f"Usage - prompt: {prompt_t}, completion: {comp_t}, total: {total_t}") model_id = "hy4-flash" مثال 1: نص غير متدفق (Chat Completions) Python: def chat_complete(user_message: str, system_prompt: Optional[str] = None) -> str: messages = [] if system_prompt: messages.append({"role": "system", "content": system_prompt}) messages.append({"role": "user", "content": user_message}) payload = { "model": model_id, "messages": messages, "temperature": 0.7, "max_tokens": 512, # يمكن إضافة "response_format": {"type": "text"} عند الحاجة } resp = post_json("/chat/completions", payload) raise_for_api_error(resp) data = resp.json() print_usage_if_any(data) return data["choices"][0]["message"]["content"] # مثال استخدام answer = chat_complete("اكتب فقرة قصيرة عن فوائد القراءة اليومية.") print(answer) مثال 2: البث (Streaming) عبر SSE Python: def chat_stream(user_message: str, system_prompt: Optional[str] = None): url = f"{BASE_URL}/chat/completions" messages = [] if system_prompt: messages.append({"role": "system", "content": system_prompt}) messages.append({"role": "user", "content": user_message}) payload = { "model": model_id, "messages": messages, "stream": True, "temperature": 0.7, "max_tokens": 512, } with requests.post(url, headers=HEADERS, json=payload, stream=True, timeout=60) as r: if r.status_code >= 400: raise_for_api_error(r) for line in r.iter_lines(decode_unicode=True): if not line: continue if line.startswith("data: "): data = line[len("data: "):].strip() if data == "[DONE]": break try: evt = json.loads(data) # النمط المتوقع: choices[].delta.content delta = evt.get("choices", [{}])[0].get("delta", {}) token = delta.get("content") if token: yield token except json.JSONDecodeError: continue # مثال استخدام for tok in chat_stream("اشرح بإيجاز مفهوم الذكاء الاصطناعي."): print(tok, end="", flush=True) print() مثال 3: توليد الصور (Images) - إما أن يعيد روابط أو بيانات base64. سنحفظ base64 إلى ملف PNG. Python: def generate_image(prompt: str, size: str = "1024x1024", filename: str = "image.png"): payload = { "prompt": prompt, "size": size, # يمكن إضافة "n": 1، "response_format": "b64_json" } resp = post_json("/images/generations", payload) raise_for_api_error(resp) data = resp.json() item = data["data"][0] if "b64_json" in item: img_b64 = item["b64_json"] img_bytes = base64.b64decode(img_b64) with open(filename, "wb") as f: f.write(img_bytes) print(f"تم حفظ الصورة في {filename}") elif "url" in item: print(f"رابط الصورة: {item['url']}") else: print("استجابة غير متوقعة لواجهة الصور.") print_usage_if_any(data) # مثال استخدام generate_image("A cozy reading nook with warm lighting, watercolor style", size="512x512", filename="reading_nook.png") مثال 4: استخراج JSON من النص - استخدم response_format لإجبار الإخراج على JSON صالح. Python: def extract_json(user_message: str, schema_hint: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: messages = [ {"role": "system", "content": "أعد فقط كائناً JSON صالحاً دون أي نص إضافي."}, {"role": "user", "content": user_message} ] payload = { "model": model_id, "messages": messages, "temperature": 0.0, "max_tokens": 512, "response_format": {"type": "json_object"} } # يمكن تمرير مخطط إرشادي عبر الرسالة، أو استخدام تعليمات واضحة داخل الـ system_prompt resp = post_json("/chat/completions", payload) raise_for_api_error(resp) data = resp.json() print_usage_if_any(data) content = data["choices"][0]["message"]["content"] return json.loads(content) # مثال استخدام doc = """ Name: Sara Ali Email: sara.ali@example.com Order ID: ORD-12345 Items: 2 """ prompt = "استخرج الحقول name, email, order_id, items من النص التالي وأعد JSON بمفاتيح مطابقة." result = extract_json(doc) print(result) مثال 5: استدعاء الأدوات (Function/Tool Calling) - سنعرّف أداة get_weather وننفذ حلقة تسيير بسيطة لمعالجة tool_calls ثم إعادة النتيجة للنموذج. Python: def get_weather(city: str, unit: str = "C") -> Dict[str, Any]: # محاكاة لاستدعاء خدمة طقس return {"city": city, "unit": unit, "temperature": 27, "condition": "Sunny"} def tool_calling_conversation(user_message: str) -> str: tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a city.", "parameters": { "type": "object", "properties": { "city": {"type": "string"}, "unit": {"type": "string", "enum": ["C", "F"]} }, "required": ["city"] } } } ] messages = [ {"role": "system", "content": "أنت مساعد ذكي يستدعي الأدوات عند الحاجة."}, {"role": "user", "content": user_message} ] # الطلب الأول للسماح للنموذج بتحديد أداة مناسبة resp = post_json("/chat/completions", { "model": model_id, "messages": messages, "tools": tools, "tool_choice": "auto", "temperature": 0.2, "max_tokens": 256 }) raise_for_api_error(resp) data = resp.json() assistant_msg = data["choices"][0]["message"] messages.append(assistant_msg) # معالجة tool_calls إن وجدت tool_calls = assistant_msg.get("tool_calls") or [] tool_map = {"get_weather": get_weather} for tc in tool_calls: fn_name = tc["function"]["name"] fn_args = json.loads(tc["function"]["arguments"] or "{}") if fn_name in tool_map: result = tool_map[fn_name](**fn_args) else: result = {"error": f"Unknown tool: {fn_name}"} # إضافة ناتج الأداة كرسالة role=tool مع نفس tool_call_id messages.append({ "role": "tool", "tool_call_id": tc.get("id"), "name": fn_name, "content": json.dumps(result, ensure_ascii=False) }) # طلب نهائي للحصول على إجابة مركّبة بعد نتائج الأداة resp2 = post_json("/chat/completions", { "model": model_id, "messages": messages, "temperature": 0.2, "max_tokens": 256 }) raise_for_api_error(resp2) data2 = resp2.json() print_usage_if_any(data2) return data2["choices"][0]["message"]["content"] # مثال استخدام final_answer = tool_calling_conversation("ما حالة الطقس الآن في الرياض بالدرجة المئوية؟") print(final_answer) معالجة الأخطاء وأفضل الممارسات - مهلات واتصالات: - استخدم timeout في جميع الطلبات. - فعّل إعادة المحاولة المتزايدة زمنياً على 429/5xx مع backoff. - التمييز بين أخطاء العميل/الخادم: - 4xx عادةً بسبب طلب سيئ، مفاتيح، حد أقصى للتوكنات، أو مدخلات غير صالحة. - 5xx مؤقتة؛ أعد المحاولة بعد فترة. - استخراج رسائل الخطأ: - حاول دوماً قراءة الحقل error.message وerror.code من الاستجابة JSON. - الحماية من الاستجابات الكبيرة: - اضبط max_tokens، واستخدم temperature منخفضة لمهام الاستخراج. - التسجيل والمراقبة: - سجّل usage لكل استجابة، مع معرفات الطلبات، لتتبّع الاستهلاك والزمن. - التتبع والمعرّفات: - أرسل request_id الخاص بك في headers إن كانت المنصة تدعم ذلك لتتبّع الطلبات. نصائح الفوترة وتقليل التكلفة - تتبع الاستخدام: - اقرأ حقول usage في كل استجابة (prompt_tokens, completion_tokens, total_tokens) وسجّلها. - التحكم في الطول: - استخدم max_tokens مناسباً، وقلّل الحشو في الـ prompts، وأعد استخدام السياق المختصر. - اختر النموذج والطور المناسب: - hy4-flash مناسب للاستجابات السريعة والتكلفة الأقل مقارنة بالنماذج الأكبر في مهام عامة واستخراجية. - الحرارة والاتساق: - temperature منخفضة (0–0.3) تقلل النصوص المشتتة وتوفر توكنات في مهام الاستخراج/الهيكلة. - البث: - يخفّض زمن الاستجابة المتصوّر للمستخدم النهائي، ويتيح إيقاف البث مبكراً عند كفاية المعلومات. - دفعات متوازنة: - إن أمكن، اجمع طلبات صغيرة في دفعات معقولة، لكن راعِ حدود المعدّل. - التحقق المبكر: - تحقق من صحة المدخلات قبل الإرسال لتقليل أخطاء 4xx المكلفة. - التخزين المؤقت: - خزّن نتائج متكررة قصيرة العمر (حيث ينطبق) لتقليل طلبات مكررة. ملاحظات - حدّث BASE_URL واسم المسارات لتطابق CometAPI لديك. - إذا كانت واجهة CometAPI لديك متوافقة مع مخطط OpenAI Chat Completions/Images، فستعمل الأنماط أعلاه مباشرة. إذا اختلف المخطط، عدّل الحقول وفق وثائق CometAPI لديك.