المصطلحات المخصصة

يكتب تحويل الكلام إلى نص ما يسمعه. فاسم بنك أو منتج أو اختصار يخرج غالبًا مكتوبًا كما يُنطق: امريتس ان بي دي بدل Emirates NBD، أو kay why see بدل KYC. أرسل مصطلحاتك في الحقل terminology، فتحمل النتيجة نسخة مصحَّحة من النص المفرّغ، مع قائمة بكل تغيير.

لا تضيع الكلمات كما سُمعت أبدًا. يبقى transcription كما فُرِّغ تمامًا، والنص المصحَّح في terminology.corrected.

متى تستخدمها

• يذكر عملاؤك أسماء علامات تجارية أو منتجات أو أماكن يكتبها النموذج العام بطريقته.
• تحتاج إلى كتابة الاختصارات حروفًا: KYC وIBAN وSWIFT.
• يُقال الاسم نفسه بالعربية والإنجليزية، وتريد له كتابة واحدة.

لا تغيّر المصطلحات ما يسمعه النموذج. فهي تصحّح النص بعد التفريغ، ولذلك لا يمكن إضافة كلمة فاتت النموذج كليًا.

مثال سريع

أرسل terminology نصَّ JSON إلى جانب file وlanguage. يعمل الحقل مع POST /v1/speech-to-text/sync وPOST /v1/speech-to-text.

curl -X POST "https://api.echonova.ai/v1/speech-to-text/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@call.mp3;type=audio/mpeg" \
  -F "language=ar" \
  -F 'terminology={"keywords": ["KYC", {"term": "Emirates NBD", "variants": ["امريتس ان بي دي"]}]}'

import json
import requests

terminology = {
    "keywords": [
        "KYC",
        {"term": "Emirates NBD", "variants": ["امريتس ان بي دي"]},
        {"term": "SWIFT", "context_words": ["transfer", "تحويل"]},
    ]
}

with open("call.mp3", "rb") as audio:
    response = requests.post(
        "https://api.echonova.ai/v1/speech-to-text/sync",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("call.mp3", audio, "audio/mpeg")},
        data={"language": "ar", "terminology": json.dumps(terminology)},
    )

data = response.json()["data"]
print(data["transcription"])              # as heard
print(data["terminology"]["corrected"])   # spelled your way

يضيف الرد كائن terminology:

{
  "transcription": "حولت المبلغ عبر السويفت إلى امريتس ان بي دي أمس.",
  "terminology": {
    "raw": "حولت المبلغ عبر السويفت إلى امريتس ان بي دي أمس.",
    "corrected": "حولت المبلغ عبر الـSWIFT إلى Emirates NBD أمس.",
    "edits": [
      { "start": 16, "end": 23, "original": "السويفت", "replacement": "الـSWIFT", "stage": "phonetic", "score": 1 },
      { "start": 28, "end": 43, "original": "امريتس ان بي دي", "replacement": "Emirates NBD", "stage": "exact", "score": 1 }
    ],
    "nearMisses": [],
    "warnings": [],
    "mapperStatus": "applied",
    "mapperVersion": "3.0.0"
  }
}

مع النقطة غير المتزامنة، يظهر الكائن نفسه في المهمة من GET /v1/speech-to-text/jobs/{jobId} حين تكتمل، وفي حدث job.completed عبر Webhook.

حقول الكلمة المفتاحية

terminology هو {"keywords": [...]}. كل كلمة مفتاحية نص عادي، أو كائن حين تريد تحكمًا أكبر.

المصطلحات والصيغ والعبارات الأخرى حتى 100 حرف لكلٍّ منها. تُتجاهل الحقول غير الواردة في هذا الجدول.

كيف تعمل المطابقة

تتجاهل المطابقة حالة الأحرف، وأشكال الهمزة العربية (أ إ آ)، وى وة، والتشكيل. المطابقة دائمًا على كلمات كاملة، ولا تتجاوز فاصلة أو نهاية جملة.

تتراوح score من 0 إلى 1. تُطبَّق المطابقات التامة والصوتية. وتُطبَّق المطابقة التقريبية حين تكون قريبة بما يكفي، أو حين تكون أقل قربًا قليلًا لكن إحدى context_words أو كلمة مفتاحية أخرى قريبة منها. والاختصارات القصيرة مثل IT أو API تُطابَق مطابقة تامة فقط، فلا تحل أبدًا محل كلمة يومية.

تبقى البادئات العربية على الكلمة: السويفت تصبح الـSWIFT، وبالكي واي سي تصبح بالـKYC. ولا تتغير الأرقام وعناوين البريد الإلكتروني وعناوين URL أبدًا.

اقرأ النتيجة

استخدم المواضع لتمييز التصحيحات في واجهتك: raw.slice(edit.start, edit.end) يساوي دائمًا edit.original.

من دون الحقل terminology لا يحتوي الرد على مفتاح terminology إطلاقًا، وتعمل النقطة تمامًا كما كانت.

التنزيلات تبقى كما سُمعت

يبني GET /v1/speech-to-text/jobs/{jobId}/export ملفات TXT وSRT وJSON من transcription ومقاطعه الموقّتة، فتحتفظ التنزيلات بالكلمات كما سُمعت. خذ terminology.corrected من المهمة للنص المصحَّح.

المطابقات القريبة

المطابقة القريبة مطابقة لم تكن الخدمة متأكدة منها بما يكفي لتطبيقها، مثل اونلاين بانكنق لـ Online Banking بدرجة 0.81. تُدرج في nearMisses مع الكلمات المسموعة والمصطلح المرشّح candidate والدرجة score، ويبقى النص دون تغيير في ذلك الموضع.

لا يُحفظ شيء بين الطلبات. لتُصحَّح مطابقة قريبة في المرة القادمة، اعرضها على شخص، وحين يؤكدها أضف الكلمات المسموعة إلى variants ذلك المصطلح في القائمة التي ترسلها.

البث المباشر

على wss://api.echonova.ai/v1/speech-to-text/stream، أرسل رسالة terminology في أي وقت. تنطبق على كل مقطع بعدها:

{
  "type": "terminology",
  "terminology": { "keywords": ["KYC", { "term": "Emirates NBD", "variants": ["امريتس ان بي دي"] }] }
}

يرد الخادم بـ {"type": "terminology.set", "active": true}، وتحمل حينها كل رسالة transcript كائن terminology لمقطعها، بمواضع داخل text ذلك المقطع. أرسلها مرة أخرى لاستبدال القائمة، أو مع "terminology": null لمسحها.

القائمة غير الصالحة تحصل على رسالة error برمز validation_failed وتُتجاهل، وتستمر الجلسة بالمصطلحات التي كانت لديها. ويجب أن تتسع الرسالة في إطار واحد حجمه 64 كيلوبايت، وهو يتسع لبضع مئات من الكلمات المفتاحية.

الحدود

المصطلحات مجانية: تكلفة الطلب واحدة بها أو من دونها.

الأخطاء

الحقل terminology الذي تتعذر قراءته يحصل على 400 قبل تفريغ أي شيء أو خصم أي رصيد.

إن فشلت المطابقة نفسها أو استغرقت وقتًا طويلًا، يكتمل التفريغ مع ذلك: تكون mapperStatus هي skipped، وcorrected مساويًا لـ raw، وتقول warnings السبب.

الأسئلة الشائعة

هل تبطئ المصطلحات التفريغ؟

بالكاد. قائمة من بضعة آلاف من الكلمات المفتاحية على مكالمة مدتها خمس دقائق تضيف أقل من ثانية بكثير.

هل يمكنني حفظ قائمة والإشارة إليها باسم؟

لا. أرسل القائمة كاملة مع كل طلب. احفظها في نظامك، وأضف إليها المطابقات القريبة المؤكدة مع الوقت.

لماذا لم يُطبَّق مصطلح؟

تحقّق من nearMisses أولًا، فربما كانت المطابقة غير مؤكدة بما يكفي. ثم أضف الكلمات المسموعة صيغةً، أو أضف context_words لتُطبَّق المطابقة القريبة حين تكون تلك الكلمات قريبة.

هل ميزة ساحة تجربة تحويل الكلام إلى نص هي الميزة نفسها؟

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

صفحات ذات صلة

• صيغ تحويل الكلام إلى نص ومخرجاته
• تفريغ الصوت المباشر
• تحويل الصوت إلى نص بشكل متزامن
• بث تحويل الكلام إلى نص
• الأخطاء