دليل استخدام LAMH
كل ما تحتاجه لربط LAMH بمساعدك الذكي في نحو 15 دقيقة: ماذا ترسل، وأين تضعه، وماذا تفعل بالنتيجة.
المحتويات
- ماذا يفعل LAMH؟
- قبل أن تبدأ
- البدء السريع في 3 خطوات
- مثال بلغة Python
- مثال بلغة JavaScript
- مثال من سطر الأوامر (curl)
- ماذا يعيد LAMH؟
- حقول الشهادة
- الأحكام: ماذا تفعل بكل مقطع؟
- إبقاء LAMH محدّثًا
- إذا تعذّر الوصول إلى LAMH
- مرجع الواجهة
- الباقات والحدود
- الأخطاء
- الأمان والخصوصية
- أسئلة شائعة
ماذا يفعل LAMH؟
مساعدك الذكي يبحث في مستنداتك، ثم يرسل المقاطع التي وجدها (نسمّيها chunks) إلى نموذج لغوي ليجيب منها. فإذا كان المقطع قديمًا، أو عُدّل، أو حُذف، أو يستند إلى نظام أو معيار لم يعد ساريًا، فسيجيب النموذج بثقة رغم ذلك. يقف LAMH بين البحث والنموذج، ويفحص كل مقطع قبل أن يصل إلى النموذج.
قبل أن تبدأ
- مفتاح API الخاص بك: يبدأ بـ
lamh_live_، ويظهر مرة واحدة عند التسجيل أو الدفع. احفظه في متغير بيئة مثلLAMH_API_KEY. - عنوان الواجهة:
https://api.mubtkrat.ai - من أين تستدعيه: من الخادم (Backend) فقط. لا تضع المفتاح أبدًا في صفحة ويب أو تطبيق جوال.
- لغة البرمجة: Python 3.8 أو أحدث (مكتبتنا بلا أي متطلبات)، أو JavaScript، أو أي لغة ترسل طلبات HTTPS.
البدء السريع في 3 خطوات
- زامن مستنداتك
أرسل كل مستند مرة واحدة على شكل قائمة مقاطع مرتبة، واستخدم المقاطع نفسها الموجودة في فهرس البحث عندك.doc_idاسم ثابت تختاره أنت للمستند (حروف إنجليزية وأرقام و. _ : / -). سيعيد LAMH رقمversion، أي إصدار المستند. وكلما تغيّر المستند فأرسله كاملًا مرة أخرى، فيسجّل LAMH الإصدار الجديد. - احفظ ثلاث علامات مع كل مقطع
في فهرس البحث (قاعدة المتجهات أو محرك البحث)، احفظ بجانب نص كل مقطع:doc_id، وchunk_noوهو ترتيب المقطع في المستند بدءًا من 0، وversion. بهذه العلامات يتعرّف LAMH على المقطع لاحقًا. - اطلب الشهادة قبل كل سؤال للنموذج
بعد أن يعيد البحث المقاطع، أرسلها إلىPOST /v1/certifyمع علاماتها ونصها. ثم ضع حقلcontextالذي يعيده LAMH في الطلب الموجّه للنموذج بدل المقاطع الخام. يحتوي هذا الحقل على النص الحالي مع تنبيه واضح لكل معلومة قديمة، ويستبعد المقاطع المحجوبة.
مثال بلغة Python
import os
from lamh_client import Lamh # download: https://lamh.mubtkrat.ai/sdk/lamh_client.py
lamh = Lamh(os.environ["LAMH_API_KEY"]) # keep the key in an environment variable
# 1) Sync: once now, and again every time a document changes
r = lamh.sync([
{"doc_id": "refund-policy", "chunks": [
"Refunds are accepted within 30 days of purchase.",
"VAT in Saudi Arabia is 15% and is included in the price.",
]},
])
version = r["versions"]["refund-policy"] # save this number with each chunk in your search index
# 2) Certify: before every model call, send the chunks your search returned
retrieved = [
{"doc_id": "refund-policy", "chunk_no": 0, "version": version,
"text": "Refunds are accepted within 30 days of purchase."},
]
out = lamh.certify(retrieved, lang="en") # lang="ar" for Arabic notes
# 3) Use: give the model out["context"] instead of the raw chunks
prompt = (
"Answer only from these sources. Respect any notice marked with a warning sign.\n\n"
+ out["context"] + "\n\nQuestion: " + question
)
مثال بلغة JavaScript
// Node 18+ or any server runtime with fetch. Never call LAMH from a browser: the key must stay secret.
const LAMH = "https://api.mubtkrat.ai";
async function lamh(method, path, body) {
const r = await fetch(LAMH + path, {
method,
headers: { Authorization: `Bearer ${process.env.LAMH_API_KEY}`, "Content-Type": "application/json" },
body: body ? JSON.stringify(body) : undefined,
});
const j = await r.json();
if (!r.ok) throw new Error(`${r.status} ${j.error.code}: ${j.error.message}`);
return j;
}
// 1) Sync
const s = await lamh("PUT", "/v1/documents", {
documents: [{ doc_id: "refund-policy", chunks: ["Refunds are accepted within 30 days of purchase."] }],
});
// 2) Certify
const out = await lamh("POST", "/v1/certify", {
lang: "en",
chunks: [{ doc_id: "refund-policy", chunk_no: 0, version: s.versions["refund-policy"],
text: "Refunds are accepted within 30 days of purchase." }],
});
// 3) Use out.context in your prompt
مثال من سطر الأوامر (curl)
export LAMH_API_KEY="lamh_live_..."
# Sync a document
curl -X PUT https://api.mubtkrat.ai/v1/documents \
-H "Authorization: Bearer $LAMH_API_KEY" -H "Content-Type: application/json" \
-d '{"documents":[{"doc_id":"refund-policy","chunks":["Refunds are accepted within 30 days of purchase."]}]}'
# Certify retrieved chunks
curl -X POST https://api.mubtkrat.ai/v1/certify \
-H "Authorization: Bearer $LAMH_API_KEY" -H "Content-Type: application/json" \
-d '{"lang":"en","chunks":[{"doc_id":"refund-policy","chunk_no":0,"version":1,"text":"Refunds are accepted within 30 days of purchase."}]}'
# Check your plan and usage
curl https://api.mubtkrat.ai/v1/usage -H "Authorization: Bearer $LAMH_API_KEY"
ماذا يعيد LAMH؟
بعد المزامنة
{"epoch": 3, "root": "0abb2816…2740", "versions": {"refund-policy": 2}, "stored_chunks": 2}
بعد طلب الشهادة
هذا رد فعلي. المقطع الأول عُدّل (صارت مدة الاسترداد 30 يومًا بدل 14)، فاستبدله LAMH بالنص الحالي. والمقطع الثاني يستند إلى ضريبة قيمة مضافة 5% في السعودية، وقد صارت 15% منذ 2020، فأضاف LAMH تنبيهًا.
{
"certificates": [
{
"ref": {"doc_id": "refund-policy", "chunk_no": 0, "version": 1},
"intact": true, "current": false, "change": "material",
"verdict": "REPLACED",
"notes": ["This passage was outdated and has been replaced with the current version since 2026-10-27."],
"text": "Refunds are accepted within 30 days of purchase.",
"basis": []
},
{
"ref": {"doc_id": "refund-policy", "chunk_no": 1, "version": 2},
"intact": true, "current": true, "change": "same",
"verdict": "VALID_WITH_NOTICE",
"basis": [{"authority": "sa.vat_rate5.1439", "status": "superseded", "effective_to": "2020-07-01",
"current_reference": "VAT 15% (from 1 July 2020)", "evidence": "https://zatca.gov.sa/…"}],
"notes": ["Note: this passage relies on VAT 5%, which is superseded since 2020-07-01; current reference: VAT 15%."],
"text": "VAT in Saudi Arabia is 5% and is included in the price."
}
],
"context": "[1] (refund-policy) ⚠ This passage was outdated and has been replaced …\nRefunds are accepted within 30 days of purchase.\n\n[2] (refund-policy) ⚠ Note: …",
"epoch": 3
}
حقول الشهادة
ref | المقطع الذي أرسلته: doc_id وchunk_no وversion. |
intact | true إذا كان النص مطابقًا للإصدار الذي زامنته (فحص تشفيري). |
current | true إذا كان أحدث إصدار من هذا المقطع. |
change | نوع التغيير: same (لا تغيير) · cosmetic (شكلي) · minor (طفيف) · material (جوهري) · removed (محذوف) · tampered (عُبث به) |
basis | الأنظمة والمعايير والإرشادات وإصدارات البرامج التي يستند إليها المقطع، مع حالتها وتاريخ انتهائها وبديلها الحالي ومصدرها الرسمي. |
verdict | الحكم، أي ماذا تفعل بالمقطع (انظر الجدول التالي). |
notes | تنبيهات مقروءة باللغة التي طلبتها. |
text | النص الذي تعطيه للنموذج (وهو النص الحالي إذا استُبدل المقطع). |
الأحكام: ماذا تفعل بكل مقطع؟
| الحكم | معناه | ماذا تفعل |
|---|---|---|
VALID | سليم وحديث، ولا شيء يستدعي التنبيه. | استخدمه. |
VALID_WITH_NOTICE | حديث، لكنه يستند إلى نظام أو معيار أُلغي أو استُبدل. | استخدمه مع التنبيه، وهو موجود أصلًا في context. |
REFRESHED | تغيّر تغيّرًا بسيطًا بعد فهرسته، فاستبدل LAMH النص الحالي به دون تنبيه. | استخدم text. |
REPLACED | تغيّر جوهري، فاستُبدل بالنص الحالي مع تنبيه. | استخدم text والتنبيه. |
BLOCKED | عُبث به، أو أن مصدره لم يعد موجودًا. | لا ترسله إلى النموذج. حقل context يستبعده تلقائيًا. |
تريد المقاطع الصالحة فقط؟
usable = lamh.usable(retrieved, lang="en") # drops BLOCKED chunks, keeps current text
chunks_for_model = [c["text"] for c in usable]
إبقاء LAMH محدّثًا
- عندما يتغيّر مستند، أرسله كاملًا مرة أخرى بنفس
doc_id، وحدّث علامةversionفي فهرس البحث عند إعادة الفهرسة. - إلى أن تعيد الفهرسة يبقى LAMH يحميك: المقاطع القديمة تعود بحكم REFRESHED أو REPLACED مع النص الحالي.
- لحذف مستندات أرسل:
{"documents": [], "delete": ["old-faq"]}، فتصير مقاطعها BLOCKED. - الحدود: 1,000 مستند في طلب المزامنة الواحد، و500 مقطع في طلب الشهادة الواحد، و4 ميجابايت للطلب.
إذا تعذّر الوصول إلى LAMH
تنتظر المكتبة حتى 10 ثوانٍ. قرّر مسبقًا ماذا يفعل مساعدك في هذه الحالة:
from lamh_client import Lamh, LamhError
try:
out = lamh.certify(retrieved, lang="en")
context = out["context"]
except (LamhError, OSError):
# LAMH unreachable or quota reached: choose your policy.
# Regulated answers (legal, medical, finance): refuse and ask the user to retry.
# General assistants: answer, but log the question for review.
context = None
مرجع الواجهة
| الطريقة | المسار | الغرض |
|---|---|---|
PUT | /v1/documents | مزامنة المستندات: {documents:[{doc_id, chunks:[…]}], delete:[doc_id]} |
POST | /v1/certify | إصدار الشهادات: {chunks:[{doc_id, chunk_no, version, text}], lang:"ar"|"en"} |
GET | /v1/documents/<doc_id> | إصدار المستند الحالي وعدد مقاطعه (لا يعيد النص أبدًا) |
GET | /v1/usage | باقتك وحدودها واستهلاكك هذا الشهر |
GET | /v1/registry?sector= | المرجعيات التي يتابعها LAMH وحالتها |
GET | /v1/root | الجذر الموقّع والمفتاح العام، لتتحقق من LAMH بنفسك |
GET | /v1/account | بيانات حسابك |
GET | /v1/health | حالة الخدمة (لا يحتاج مفتاحًا) |
كل طلب ما عدا /v1/health يحتاج الترويسة Authorization: Bearer <مفتاحك>.
الباقات والحدود
| الباقة | مقاطع معتمدة شهريًا | مقاطع مخزّنة | طلبات في الثانية |
|---|---|---|---|
| التجربة (14 يومًا) | 10,000 | 20,000 | 5 |
| Starter | 50,000 | 25,000 | 10 |
| Pro | 1,000,000 | 500,000 | 50 |
| المؤسسات | 50,000,000 | 20,000,000 | 500 |
اعرف أرقامك أنت في أي وقت عبر GET /v1/usage.
الأخطاء
تعود الأخطاء بهذا الشكل: {"error": {"code": "…", "message": "…"}}.
| HTTP | الرمز | ماذا تفعل |
|---|---|---|
| 400 | bad_chunk / bad_chunks / bad_doc_id / bad_json | صحّح محتوى الطلب: كل مقطع يحتاج doc_id وchunk_no وversion وtext. |
| 401 | unauthorized | المفتاح مفقود، أو فيه خطأ، أو أُلغي. |
| 402 | certify_quota / storage_quota | بلغت حد الشهر. رقِّ باقتك أو انتظر الشهر التالي. |
| 402 | subscription_expired | جدّد اشتراكك من الموقع. |
| 413 | too_large | قسّم الطلب (الحد 4 ميجابايت). |
| 429 | rate_limited / write_rate_limited | طلبات كثيرة. انتظر ثوانيَ ثم أعد المحاولة. |
| 503 | integrity_failure | راسل [email protected]. |
الأمان والخصوصية
- مقاطعك مخزّنة مشفّرة بمفتاح خاص بحسابك وحده. ومفاتيح API لا تُخزَّن أبدًا، بل بصمتها فقط.
- أي تغيير في بياناتك المخزّنة من خارج LAMH يُكتشف، فتتوقف الخدمة عن حسابك حتى يُفحص.
- تستطيع التحقق من السجل الموقّع بنفسك عبر
GET /v1/root. - البيانات مستضافة في الاتحاد الأوروبي (فرانكفورت). انظر اتفاقية معالجة البيانات وسياسة الخصوصية.
أسئلة شائعة
هل يحل LAMH محل قاعدة المتجهات أو النموذج؟
لا. أبقِ البحث والنموذج كما هما، فـLAMH مجرد استدعاء واحد بينهما.
مع أي نموذج أو إطار عمل يعمل؟
مع أيٍّ منها: OpenAI وClaude وGemini وLlama وLangChain وLlamaIndex، أو كودك الخاص. LAMH يحتاج فقط نص المقطع وعلاماته الثلاث.
هل يجب أن أرسل كل مستنداتي؟
فقط المستندات التي يبحث فيها مساعدك، لأن LAMH يقارن المقاطع المسترجعة بها.
ما اللغات المدعومة؟
المقاطع بأي لغة. والتنبيهات بالعربية أو الإنجليزية حسب حقل lang.
ما سرعته؟
عادةً بضعة أجزاء من الألف من الثانية لكل مقطع، وهذا أقل بكثير من الوقت الذي يستغرقه النموذج ليجيب.