TL;DR
يتوفر Gemini 4 Hydrogen API عبر واجهة Gemini من Google وعبر بوابات طرف ثالث مدعومة مثل CometAPI. اختر المسار أولًا: استخدم Google للحصول على ميزات خاصة بالمزوّد والتحكم في الحساب، أو استخدم CometAPI عندما تريد بوابة موحّدة للنماذج أو عميلًا متوافقًا مع OpenAI. ابدأ بطلب نصي صغير، ثم أضِف البث، وسجل المحادثة، والملفات، والأدوات.
ستحتاج إلى Python 3.10 أو أحدث، ومفتاح للمسار المُختار، وإمكانية الوصول إلى gemini-4-hydrogen. المثال الاختياري لجافاسكريبت يستخدم Node.js 22 أو أحدث. احتفظ ببيانات الاعتماد في بيئة الخادم طوال مدة الدليل.
Key Takeaways
- استخدم
gemini-4-hydrogenكمعرّف النموذج لواجهة Gemini 4 Hydrogen. - لدى Google وCometAPI بيانات اعتماد وفوترة منفصلة. طابِق المفتاح مع نقطة النهاية التي تحددها.
- ابدأ بـ GenerateContent الأصلي؛ استخدم الواجهة المتوافقة مع OpenAI الخاصة بـ CometAPI عندما تناسب عميل دردشة قائم.
- احتفظ بالاستجابة الكاملة للنموذج في سجل متعدد الأدوار، بما في ذلك التوقيعات، قبل إرجاع متابعة أو نتيجة أداة.
- قارن الاستخدام الفعلي للرموز والمهام المكتملة عند اختيار المسار؛ يظهر مثال سعر الرموز القياسي في قسم التسعير.
What Is the Gemini 4 Hydrogen API?
قدمت Google Hydrogen في 12 نوفمبر 2026. تقبل الواجهة مطالبات وملفات مدعومة، ثم تُرجع نصًا مولّدًا أو استدعاءات دوال مُهيكلة لتتعامل معها تطبيقك. لا تحتاج لاستضافة النموذج بنفسك.
ابدأ بطلب نصي فقط وتحقق من النص المُرجع وسبب الإنهاء واستخدام الرموز قبل إضافة الأدوات أو الملفات. بعد أن يعمل ذلك، أضِف حالة محادثة أو أداة أعمال للقراءة فقط بدلًا من بناء سير العمل بالكامل دفعة واحدة.
Gemini 4 Hydrogen API specifications
| المواصفات | قدرات النموذج الموثّقة من Google |
|---|---|
| معرّف النموذج | gemini-4-hydrogen |
| الإدخال | نصوص، صور، صوت، فيديو، ومستندات مدعومة |
| الإخراج | نص، مع أجزاء استدعاء دوال مُهيكلة عند استخدام الأدوات |
| ميزانية سياق موحّدة | 1,048,576 من الرموز عبر الإدخال والإخراج |
| مقطع الإخراج الأمامي الفردي | حتى 65,536 من الرموز، بما في ذلك الاستدلال واستدعاءات الدوال |
| ميزات التطبيق | التحكم في مستوى التفكير، إخراج مُهيكل، واستدعاء الدوال |
هذه قدرات للنموذج، وليست ضمانًا بأن كل بوابة تعرض كل ميزة لدى المزوّد. الأمثلة أدناه تستخدم حقول طلب قياسية وأجيال أمامية قصيرة.
Google Official API vs CometAPI
يدعم كلا المسارين طلبات Gemini، لكنهما يستخدمان نقاط نهاية وبيانات اعتماد وأنظمة فوترة مختلفة. استخدم Google للحصول على ميزات خاصة بالمزوّد؛ استخدم CometAPI للوصول الموحّد إلى النماذج أو لعميل متوافق موجود.
| قرار | Google Gemini Developer API | CometAPI Gemini integration |
|---|---|---|
| المضيف الأصلي للواجهة | generativelanguage.googleapis.com | api.cometapi.com |
| مفتاح الواجهة في هذا الدليل | GEMINI_API_KEY | COMETAPI_KEY |
| الحساب والفوترة | تُدار عبر Google | تُدار عبر CometAPI |
| أفضل نقطة بداية | ميزات خاصة بـ Google والتحكم في الحساب | وصول موحّد للنماذج أو عميل متوافق مع OpenAI موجود |
حافظ على نفس المطالبة وميزانية الإخراج عند التحقق من المسارين بحيث تكون النتائج مفيدة للمقارنة. تبقى بدائل جافاسكريبت والواجهة المتوافقة مع OpenAI مُهيأة صراحةً لـ CometAPI.
How to Use Gemini 4 Hydrogen API Step by Step?
Step 1: Create an API key
بالنسبة إلى CometAPI، أنشئ حسابًا واستخرج مفتاحًا من API token console. للوصول المباشر عبر Google، أنشئ مفتاح Gemini API في Google AI Studio. أكّد الوصول إلى النموذج وحالة الفوترة أو الحصة المتاحة للحساب المحدد.
خزّن المفتاح بأمان. لا يمكن لمفتاح CometAPI مصادقة طلب إلى نقطة نهاية Google، ولا يمكن لمفتاح Google مصادقة طلب CometAPI.
عيّن المفتاح للمسار الذي اخترته في Bash؛ تحتاج فقط إلى واحد من هذه التعريفات.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
عيّن المفتاح المقابل في PowerShell على Windows.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
Step 2: Send a first request with cURL
أرسل طلبًا نصيًا أصليًا عبر CometAPI من طرفية Bash.
curl "https://api.cometapi.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
بديلًا عن ذلك، أرسل نفس الطلب الأصلي مباشرةً إلى Google باستخدام مفتاح Google API.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
بعد نجاح الطلب، تحقّق من ثلاثة حقول: candidates[0].content.parts للنص المرئي، وfinishReason لحالة الإنهاء، وusageMetadata لاستخدام الرموز. أصلِح أخطاء المصادقة أو الطلب قبل إضافة المزيد من كود التطبيق.
Step 3: Configure the Python Client and Send a Request
ثبّت الحزم المستخدمة في أمثلة Python.
python -m pip install requests openai
احفظ المساعد التالي باسم hydrogen_client.py. أبقِ PROVIDER مضبوطًا على cometapi لـ CometAPI، أو اضبطه على google للوصول المباشر إلى Gemini Developer API. تستورد الأمثلة الأصلية لاحقًا هذا الملف، لذا فهي تحتفظ بالمسار المحدد.
اضبط نقطة النهاية المختارة وعرّف مساعدات طلب ونص قابلة لإعادة الاستخدام.
import os
import requests
MODEL = "gemini-4-hydrogen"
PROVIDER = "cometapi" # Change to "google" for direct access.
ROUTES = {
"cometapi": ("https://api.cometapi.com", "COMETAPI_KEY"),
"google": ("https://generativelanguage.googleapis.com", "GEMINI_API_KEY"),
}
BASE_URL, KEY_NAME = ROUTES[PROVIDER]
API_KEY = os.environ[KEY_NAME]
URL = f"{BASE_URL}/v1beta/models/{MODEL}:generateContent"
def generate(payload):
response = requests.post(
URL,
headers={"x-goog-api-key": API_KEY},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
def visible_text(data):
candidates = data.get("candidates") or []
if not candidates:
raise ValueError("No candidate returned; inspect promptFeedback.")
candidate = candidates[0]
parts = candidate.get("content", {}).get("parts", [])
text = "".join(
part.get("text", "") for part in parts
if not part.get("thought", False)
)
if not text:
raise ValueError(
f"No visible text; inspect parts and finishReason: "
f"{candidate.get('finishReason')}"
)
return text
احفظ ما يلي باسم hydrogen.py بجانب المساعد. يطبع الإجابة وسبب الإنهاء والاستخدام حتى تتمكن من تمييز الإجابة المكتملة عن إخراج توقف بسبب حد الرموز.
أرسل طلبًا نصيًا باستخدام المزوّد المُعد.
from hydrogen_client import generate, visible_text
data = generate({
"contents": [{"role": "user", "parts": [{
"text": "Explain API rate limiting in three sentences."
}]}],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
},
})
print(visible_text(data))
candidate = data["candidates"][0]
print("Finish reason:", candidate.get("finishReason"))
print("Usage:", data.get("usageMetadata", {}))
شغّل البرنامج النصي في الطرفية حيث قمت بضبط مفتاح الواجهة المحدد.
python hydrogen.py
اقرأ الإجابة، ثم تحقق من finishReason لمعرفة سبب توقف التوليد. في usageMetadata، تحقّق من عدد الرموز التي استخدمها الطلب. يعني MAX_TOKENS أن الاستجابة قد تكون غير مكتملة، حتى عندما ينجح طلب HTTP.
Use JavaScript or an OpenAI-Compatible Client
اختر المثال الذي يناسب تطبيقك. يرسل مثال Node.js طلب Gemini أصليًا. إذا كان تطبيقك يستخدم بالفعل OpenAI SDK، فتخطّ إلى مثال Python أدناه.
JavaScript with Node.js
احفظ ما يلي باسم hydrogen.js ثم شغّل node hydrogen.js. يرسل نفس شكل الطلب الأصلي ويستخرج كل أجزاء النص المرئي.
أرسل طلب GenerateContent أصليًا من Node.js.
const apiKey = process.env.COMETAPI_KEY;
if (!apiKey) throw new Error("Set COMETAPI_KEY before running this script.");
const baseUrl = "https://api.cometapi.com";
const model = "gemini-4-hydrogen";
async function main() {
const response = await fetch(
`${baseUrl}/v1beta/models/${model}:generateContent`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-goog-api-key": apiKey
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [
{
text: "Explain how an AI coding agent works."
}
]
}
],
generationConfig: {
maxOutputTokens: 4096,
thinkingConfig: {
thinkingLevel: "MEDIUM"
}
}
})
}
);
if (!response.ok) {
throw new Error(
`API error: ${response.status} ${await response.text()}`
);
}
const data = await response.json();
const candidate = data.candidates?.[0];
const text = (candidate?.content?.parts || [])
.filter(part => !part.thought)
.map(part => part.text || "")
.join("");
if (!text) {
throw new Error(`No visible text; finishReason=${candidate?.finishReason}`);
}
console.log(text);
}
main().catch(console.error);
Python with the OpenAI SDK
إذا كان تطبيقك يستخدم بالفعل OpenAI SDK، فإن CometAPI تعرض أيضًا POST /v1/chat/completions. أبسط هجرة هي تغيير مفتاح الواجهة وعنوان الأساس ومعرّف النموذج. استخدم هذا المسار لسير عمل الدردشة الشائعة؛ استخدم نقطة نهاية Gemini الأصلية عندما تحتاج إلى حقول خاصة بـ Gemini لدى المزوّد.
أنشئ طلب Chat Completions عبر CometAPI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
response = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": "Explain how an AI coding agent works."
}
]
)
print(response.choices[0].message.content)
تستخدم الأمثلة الأصلية contents وgenerationConfig؛ بينما يستخدم Chat Completions messages وحقول طلب خاصة به. أبقِ كل طلب في صيغة واحدة بدلًا من نسخ الحقول الأصلية إلى استدعاء SDK لا يقبلها.
Advanced Gemini 4 Hydrogen API Features
تعيد الأمثلة التالية استخدام hydrogen_client.py من قسم الإعداد، لذا فهي تعمل مع المزوّد المحدد في PROVIDER. يستخدم مثال البث أدناه عميل CometAPI Chat Completions المنفصل، وهو مناسب لتطبيق متوافق مع OpenAI موجود.
Configure reasoning and structured output
استخدم generationConfig لضبط thinkingConfig.thinkingLevel على LOW أو MEDIUM أو HIGH أو XHIGH. اختر ميزانية إخراج تترك مساحة لكل من التفكير والإجابة المرئية. عندما يتوقع التطبيق JSON، استخدم responseMimeType وresponseSchema بدلًا من الاعتماد فقط على طلب تنسيق باللغة الطبيعية.
اضبط ميزانية الإخراج ومستوى التفكير لطلب أصلي.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Stream responses through CometAPI
يُرجع البث المحتوى المُولّد تدريجيًا بدلًا من انتظار الإجابة الكاملة. وهو مفيد لواجهات الدردشة ومساعدي البرمجة والتطبيقات التي يهمّها زمن الاستجابة المُدرَك.
توثّق CometAPI streaming Chat Completions with stream=true. يتعامل مثال Python مع المقاطع الخالية من choices، والتي يمكن أن تظهر في الاستجابات المتدفقة.
اطبع النص عند وصوله عبر نقطة النهاية المتوافقة مع OpenAI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
stream = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": (
"Write a Python function that validates an email "
"address and explain the main checks."
)
}
],
stream=True
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta and delta.content:
print(delta.content, end="", flush=True)
print()
بالنسبة لعميل أصلي، توثّق CometAPI streamGenerateContent with Server-Sent Events. يُرجع ذلك المسار كائنات استجابة GenerateContent بدلًا من دلتا Chat Completions. أبقِ المحلّل مُطابقًا للمسار؛ قد يختلف سلوك البث بين نقطة نهاية Gemini الأصلية والبوابة المتوافقة مع OpenAI. اختبر مسار Hydrogen الدقيق الذي يستخدمه تطبيقك قبل ترحيل عميل بث موجود.
Preserve multi-turn conversation history
أرسل الأدوار السابقة للمستخدم والنموذج مع الطلب التالي. احتفظ بكائن محتوى النموذج الكامل بدلًا من إعادة بنائه من النص المرئي؛ فهذا يحافظ على البيانات الوصفية المُرجعة للدور التالي. احفظ المثال باسم hydrogen_history.py بجانب المساعد المشترك.
نفّذ طلبين مترابطين مع الحفاظ على الاستجابة الأولى الكاملة للنموذج.
from hydrogen_client import generate, visible_text
history = [{"role": "user", "parts": [{
"text": "Suggest a simple queue-based background job architecture."
}]}]
config = {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
}
first = generate({"contents": history, "generationConfig": config})
print(visible_text(first))
candidate = first["candidates"][0]
if candidate.get("finishReason") != "STOP":
raise RuntimeError("The first turn did not finish normally.")
history.append(candidate["content"])
history.append({"role": "user", "parts": [{
"text": "Now identify three failure scenarios in that design."
}]})
second = generate({"contents": history, "generationConfig": config})
print(visible_text(second))
print("Finish reason:", second["candidates"][0].get("finishReason"))
شغّل python hydrogen_history.py. ينبغي أن تتناول الإجابة الثانية التصميم من الدور الأول. أبقِ بادئة المحادثة المبكرة دون تغيير في هذا المثال؛ التطبيقات طويلة الأمد تحتاج إلى سياسة منفصلة للضغط وحدود السياق.
Send images and PDFs
يدعم Hydrogen فهم الصور والمستندات. في صيغة الطلب الأصلية الخاصة بـ Gemini، أضِف جزء inlineData إلى جانب التعليمات النصية. هذا مفيد لتحليل لقطات الشاشة ومخططات البنية ونماذج الممسوحة وتقارير الاستخراج.
احفظ هذا المثال باسم analyze_file.py بجانب hydrogen_client.py. يرسل صورة محلية أو PDF واحدًا، بحيث يمكنك إعادة استخدام نفس الكود لكلا الإدخالين. استخدم ملفًا صغيرًا في الطلب الأول؛ يزيد Base64 من حجم الطلب.
حلّل ملف PNG أو JPEG أو PDF محليًا باستخدام العميل الأصلي المشترك.
import base64
import sys
from pathlib import Path
from hydrogen_client import generate, visible_text
path = Path(sys.argv[1])
mime_types = {
".png": "image/png", ".jpg": "image/jpeg",
".jpeg": "image/jpeg", ".pdf": "application/pdf",
}
mime_type = mime_types.get(path.suffix.lower())
if mime_type is None:
raise ValueError("Choose a PNG, JPEG, or PDF file.")
data = generate({
"contents": [{"role": "user", "parts": [
{"text": "Summarize this file and identify the key findings."},
{"inlineData": {
"mimeType": mime_type,
"data": base64.b64encode(path.read_bytes()).decode("ascii"),
}},
]}],
"generationConfig": {"maxOutputTokens": 4096},
})
print(visible_text(data))
شغّل مثال الملف باستخدام مستندك أو صورتك الخاصة.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
يجب أن تتطابق بايتات الملف مع نوع MIME المُعلن. لا يحول تغيير امتداد اسم الملف نوعه. إذا تم رفض رفع ما، فافحص الخطأ لمعرفة حد الحجم أو الصيغة قبل محاولة مرة أخرى؛ لا تفترض أن URI لملف مُستضاف لدى Google يمكن الوصول إليه عبر بوابة طرف ثالث.
Connect application-controlled tools
يتيح استدعاء الدوال للنموذج طلب تنفيذ عملية تقوم بها تطبيقك. يُرجع النموذج استدعاء دالة مُهيكلًا؛ يقوم تطبيقك بالتحقق من الوسائط وتنفيذ الدالة وإرسال النتيجة مرة أخرى.
يستخدم هذا المثال قاعدة بيانات طلبات صغيرة وخيالية. احفظه باسم order_agent.py بجانب العميل المشترك. ينفّذ رحلة الذهاب والإياب، ويحدّ الحلقة بأربعة طلبات، ويُحافظ على محتوى النموذج الكامل—بما في ذلك أي توقيعات مُعادة—بين الأدوار.
شغّل حلقة استدعاء دوال محدودة مقابل قاعدة بيانات عرض محلية.
from hydrogen_client import generate, visible_text
orders = {"DEMO-1001": {"status": "shipped", "carrier": "Example Carrier"}}
tools = [{"functionDeclarations": [{
"name": "lookup_order",
"description": "Retrieve a demonstration order by its order ID.",
"parameters": {
"type": "OBJECT",
"properties": {"order_id": {"type": "STRING"}},
"required": ["order_id"],
},
}]}]
history = [{"role": "user", "parts": [{
"text": "Use lookup_order to check the status of DEMO-1001."
}]}]
for _ in range(4):
data = generate({
"contents": history,
"tools": tools,
"generationConfig": {"maxOutputTokens": 4096},
})
candidates = data.get("candidates") or []
if not candidates or not candidates[0].get("content"):
raise RuntimeError("No model content returned.")
model_content = candidates[0]["content"]
calls = [
part["functionCall"] for part in model_content.get("parts", [])
if "functionCall" in part
]
if not calls:
print(visible_text(data))
break
history.append(model_content) # Preserve all parts and signatures.
results = []
for call in calls:
args = call.get("args", {})
order_id = args.get("order_id") if isinstance(args, dict) else None
if call.get("name") != "lookup_order":
raise ValueError("Unexpected function name.")
if not isinstance(order_id, str) or not order_id:
raise ValueError("order_id must be a non-empty string.")
result = orders.get(order_id, {"error": "Order not found"})
reply = {"name": call["name"], "response": result}
if "id" in call:
reply["id"] = call["id"]
results.append({"functionResponse": reply})
history.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool-call limit reached before a final answer.")
شغّل python order_agent.py. ينبغي أن تعكس الإجابة النهائية السجل المحلي لـ DEMO-1001. في خدمة حقيقية، قم بتخويل المستخدم قبل الوصول إلى طلب؛ اختيار النموذج لمعرّف طلب ليس دليلًا على الإذن.
How Much Does Gemini 4 Hydrogen API Cost?
الأسعار أدناه بالدولار الأمريكي لكل مليون رمز، تم التحقق منها في 17 نوفمبر 2026. إنها تقارن الإدخال والإخراج القياسي غير المُخزَّن مؤقتًا، وليس الدُفعات أو الأولوية أو الإدخال المُخزَّن مؤقتًا أو استخدام الأدوات المُفوترة بشكل منفصل.
| نوع الرموز | Google Global Standard | Gemini 4 Hydrogen API في CometAPI |
|---|---|---|
| رموز الإدخال / 1M | $1.50 | $1.20 |
| رموز الإخراج / 1M | $7.50 | $6.00 |
بالنسبة إلى 100,000 رمز إدخال و10,000 رمز إخراج مُفوّر، فإن تقدير CometAPI هو 0.1 × $1.20 + 0.01 × $6.00 = $0.18. تكلف نفس الأحجام وفق الأسعار القياسية المُدرجة لدى Google مبلغ $0.225، بفارق 20%. ضمّن رموز التفكير في استخدام الإخراج وتحقق من الاستخدام المُفوّر في حسابك عند تقدير سير عمل حقيقي.
How Do You Migrate to Gemini 4 Hydrogen API?
What Changes When Migrating from Gemini 3.8 Flash?
قبل تغيير معرّف النموذج، تحقّق من إعدادات الاستدلال، وميزانية السياق، وسجل المحادثة الذي يرسله عميلك مع كل طلب.
| تفاصيل التكامل | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| مستوى التفكير الافتراضي | MEDIUM | HIGH |
| محاسبة السياق | حدود منفصلة للإدخال والإخراج | ميزانية إدخال/إخراج مشتركة واحدة |
| حالة متعددة الدورات | راجع معالجة السجل لدى العميل الحالي | حافظ على أجزاء النموذج الكاملة والتوقيعات؛ تتطلب تعديلات البادئة معالجة خاصة |
تُعد تغييرات الهجرة الموثّقة مهمة بالأخص عندما يعتمد تطبيقك على القيم الافتراضية، أو يضغط السجل، أو يُشغّل عدة دورات أدوات. اضبط الاستدلال صراحةً واختبر سير عمل قصير قائم قبل تغيير نموذج الإنتاج.
Update an existing integration
أنشئ تهيئة اختبارية بمعرّف النموذج الجديد مع إبقاء مفتاحه ونقطة النهاية معًا. شغّل نفس سير العمل التمثيلي بالتهيئتين حتى تتمكن من مقارنة سلوكهما.
- أرسل طلبًا نصيًا جديدًا وتحقق من سبب الإنهاء واستخدام الرموز.
- أعد تشغيل مهمة متعددة الأدوار ورحلة أدوات ذهابًا وإيابًا باستخدام كائنات استجابة نموذج كاملة.
- أزِل عناصر التحكم غير المتوافقة المدرجة في قسم القيود قبل مقارنة نتائج الطلب.
- اختبر مسار التراجع في محادثة جديدة؛ لا تفترض أن نموذجًا آخر يقبل بيانات الاستدلال المحفوظة لدى Hydrogen.
Decide whether the migration helps your workload
اعتمد التهيئة الجديدة عندما تستوفي جودة المهمة وأهداف زمن الاستجابة بتكلفة مقبولة لكل مهمة مكتملة. إذا كان العميل الحالي يستوفي تلك الأهداف بالفعل، فاستخدم تجربة محدودة لإثبات الفائدة قبل نقل كل الطلبات. حافظ على المطالبات والمدخلات ومعايير القياس متسقة أثناء التقييم.
Gemini 4 Hydrogen API Limitations
يصف دليل مطوّري Hydrogen قيودًا تؤثر على العملاء الحاليين. عالجها في بناء الطلب بدلًا من إعادة محاولة نفس الحمولة المرفوضة.
- حقول غير مدعومة: أزِل thinkingBudget، وthinkingLevel المضبوط على MINIMAL، وfrequencyPenalty، وpresencePenalty، وcandidateCount أكبر من واحد.
- إعدادات أخذ العينات المُتجاهلة: لا تتحكم درجات حرارة مخصصة أو topP أو topK في إخراج Hydrogen.
- التخزين المؤقت: cachedContent الصريح غير مدعوم. يمكن أن تستخدم بادئات المطالبات الثابتة تخزينًا مؤقتًا ضمنيًا، لكن ذلك لا يُنشئ خصم تخزين مؤقت خاص بالبوابة.
- إخراج طويل: ينفّذ العميل النموذجي في هذا الدليل طلبًا متزامنًا فقط. لا يغطي فكًا طويلًا في الخلفية أو سير عمل استمرار خاص بالمزوّد.
- تغييرات المحادثة: تعديل مطالبات سابقة أو تعريفات أدوات يمكن أن يُبطل حالة الاستدلال. حافظ على البادئة، أو نفّذ سلوك عدم تطابق البادئة الموثّق للمسار المحدد.
Common setup checks
| العَرَض | أول فحص |
|---|---|
| 401 أو 403 | تأكد من أن بيانات الاعتماد تخص نقطة النهاية ولديها وصول إلى النموذج المحدد. |
| 400 | اقرأ جسم الخطأ؛ افحص الحقول غير المدعومة وJSON المشوّه وبيانات وصف المحادثة. |
| لا نص مرئي | افحص promptFeedback وأجزاء candidate وfinishReason؛ قد تكون الاستجابة محظورة أو غير مكتملة أو تطلب أداة. |
| MAX_TOKENS | اعتبر النص غير مكتملٍ محتملًا وراجع ميزانية الإخراج قبل قبوله. |
| رُفض طلب ملف | تحقّق من نوع MIME الفعلي وحدّ الحمولة للمسار المحدد. |
للفشل غير المتوقع، سجّل النموذج والمسار والحالة والطابع الزمني ومعرّف الطلب عندما يكون متاحًا. أبقِ مفاتيح الواجهة ومحتويات الملفات الحساسة خارج السجلات الروتينية.
FAQ
How should I retry Gemini 4 Hydrogen API rate-limit errors?
بالنسبة إلى HTTP 429، خفّض التوازي وأعد المحاولة مع ارتداد أُسّي وتباين، بعدد محاولات أقصى ثابت. احتفظ بمعرّف الطلب عندما توفره البوابة. لا تُعد محاولة طلبات غير صالحة أو إخفاقات المصادقة دون تغيير؛ يُميّز دليل أخطاء CometAPI واستراتيجية إعادة المحاولة تلك عن الإخفاقات العابرة. يمكن أن يحدث انتهاء المهلة بعد بدء المعالجة، لذا احمِ أي إجراء على جانب التطبيق من التنفيذ المكرر.
Can I call Gemini 4 Hydrogen API directly from a web app?
مرّر الطلبات عبر الواجهة الخلفية الخاصة بك. يمكن استخراج مفتاح مضمّن في جافاسكريبت الواجهة الأمامية من قبل الزائرين، حتى لو تم تجميع الكود أو تصغيره. دع الواجهة الخلفية تصادق المستخدمين وتطبق حدود الاستخدام وترسل طلب النموذج. بالنسبة للبث، مرّر الاستجابة المتزايدة إلى المتصفح دون كشف مفتاح الواجهة الصاعدة.
How should I handle an interrupted Gemini 4 Hydrogen stream?
اعتبر النص المستلم نتيجةً جزئية حتى تكتمل الاستجابة. يبدأ طلب جديد توليدًا جديدًا؛ لا يستأنف تلقائيًا البث المقطوع عند نفس الرمز. احتفظ بالإخراج الجزئي منفصلًا عن إجابة معاد محاولة، ولا تُنفّذ إجراءات من JSON غير مكتمل أو وسيطات أدوات غير منتهية. قدّم إجراء إعادة محاولة ظاهرًا بدلًا من ربط جيلين بصمت.
Conclusion
استخدم مهمة تمثيلية كفحص قبول أول: ينبغي أن ينجح الطلب، وأن يستخرج التطبيق النتيجة المقصودة، وأن يتناسب استخدام الرموز المسجّل مع ميزانيتك. أضِف ميزة واحدة في كل مرة واحتفظ بهذا الفحص في مجموعة تكاملاتك. إن العميل الصغير والقابل للملاحظة أسهل في التوسيع من سير عمل كبير يصعب تتبّع إخفاقاته.

