Alice Beceri Belgeleri: Bölümler Arasında Hızlı Bir Yolculuk

Resmi Alice beceri belgeleri, geliştiriciler için «Dialoglar → Alice» bölümünde yer alır; hızlı başlangıç ile başlamak, ardından istek/yanıt formatına (webhook) geçmek ve ancak ondan sonra yayınlama ve moderasyon gereksinimlerine yönelmek en doğrusudur. Temel giriş noktası: https://yandex.ru/dev/dialogs/alice/doc/ru/.

Belgeleri nerede bulmalı ve ilk olarak neyi açmalı

Belgeler içinde gezinirken «menüye» göre değil, göreve göre hareket etmek daha kullanışlıdır:

1. İlk çalışan prototipi oluşturmak
   Beceri oluşturma, endpoint/webhook bağlama ve minimum senaryo (selamlama → komut → çıkış) ile ilgili bölümlere bakın.

2. Veri alışveriş formatını anlamak
   JSON istekleri ve yanıtlarının açıklamasını açın: gelen olayın yapısı, oturum alanları, kullanıcı verileri, yanıt seçenekleri (metin, düğmeler, kartlar).

3. Yayına hazırlanmak
   Beceri kartı gereksinimleri, kısıtlamalar, moderasyon kuralları ve sürüm durumları (taslak/moderasyonda/yayınlandı) hakkında bilgi edinin.

Bir beceri nasıl çalışır: webhook, oturumlar ve yanıt

Çoğu beceri «Alice ↔ sizin backend'iniz» şemasına göre çalışır:

• kullanıcı bir cümle söyler;
• platform bir JSON isteği oluşturur ve bunu webhook'unuza gönderir;
• siz Alice'in seslendireceği (ve ekran varsa göstereceği) JSON yanıtını döndürürsünüz.

Kod yazmadan önce belgelerde kontrol edilmesi gereken önemli noktalar:

• Yanıt zaman aşımı: Backend çok yavaş yanıt verirse diyalog kesilir. Hızlı yanıt ve/veya önbellek planlayın.
• Oturum ve durum: Diyalogun devamının bozulmaması için bağlamı (senaryo adımı, seçilen parametreler) uygun şekilde saklayın.
• Diyalogu sonlandırma: Kullanıcının becerinin «kapatıldığını» anlaması için bitiş işaretini doğru ayarlayın.
• Çok modluluk: Düğmeler/kartlar kullanıyorsanız, sesli eşdeğerini de düşünün (kullanıcı ekransız olabilir).

Mini seçim: Backend'i nerede tutmalı

Niyetler ve NLU: Cümleleri mantıkla nasıl eşleştirmeli

Niyet, kullanıcının «amacı»dır (örneğin: hava durumunu öğrenmek, görev eklemek, kuralları tekrarlamak). Belgelerde genellikle platformun tanıma sonucunu nasıl ilettiği ve senaryo dalını seçmek için hangi istek alanlarının kullanılabileceği açıklanır.

Hata ayıklama sürecinde zaman kazandıran pratik kurallar:

• Tek bir «evrensel» niyet yerine birkaç dar kapsamlı niyet oluşturun.
• Fallback (yedek) dalı ekleyin: Cümle tanınmadığında ne söylenecek (ve nazikçe yeniden ifade etmesi nasıl istenecek).
• Cümle varyasyonlarını gerçek insanlardan toplayın: Ana eylemler için 20–50 cümle, kafadan çıkan «ideal» örneklerden çoğu zaman daha fazla fayda sağlar.

Test etme, yayınlama ve moderasyon: Kontrol listesi

Moderasyona göndermeden önce kısa bir kontrol listesinden geçirin:

• Mutlu yol (Happy path): Tüm ana komutlar maksimum 1–2 netleştirme ile çalışıyor.
• Giriş hataları: Eksik cümleler, «yanlış kelime», duraksamalar, konu değişikliği.
• Boş veriler: Sonuç yok, liste boş, dış sistem erişilemez.
• Tekrarlar: Kullanıcı tekrar etmesini, geri dönmesini veya iptal etmesini istiyor.
• Yanıt metinleri: Kısa, resmi dilden uzak, «sonraki adımda ne söylenebileceğine» dair ipucu içeren.

Beceri kartı için önceden hazırlayın: anlaşılır bir açıklama, doğru komut örnekleri, varsa kısıtlamalar/koşullar ve bunların becerinin gerçek davranışıyla uyumlu olduğundan emin olun.

Sık yapılan hatalar

• Çok yavaş yanıt vermek (önbellek/hızlı «ara» senaryo olmadan) ve diyalog kesintileri yaşamak.
• Durumu saklamamak: İkinci soruda beceri konuyu «unutur».
• Fallback mantığı olmaması: Kullanıcı farklı söylediğinde beceri «anlamadım» döngüsüne girer.
• Aşırı uzun yanıtlar: Sesli arayüz, uzun metin yığınlarını daha kötü tolere eder.
• Beceri kartındaki komutların gerçeklikle uyuşmaması (moderasyon ve yorumlar bunu hızla ortaya çıkarır).

SSS

Webhook üzerinde bir beceri yapıyorsam ayrı bir belge bölümüne ihtiyacım var mı?

Evet. «Sadece metin döndürüyor» olsanız bile, gelen isteğin yapısı, yanıt formatı, diyalog sonlandırma yönetimi, zaman kısıtlamaları ve öğelerin (düğmeler/kartlar) görüntülenme kuralları kritik öneme sahiptir.

Zaman azsa nereden başlamalı?

Minimum bir senaryo oluşturun: selamlama → 2–3 komut → yardım → çıkış. Ardından istek/yanıt protokolü bölümünü açın ve yanıtları doğru formata getirin; bu, çalışan bir prototipe en hızlı ulaşmanızı sağlar.

Yayınlanmadan önce hangisi daha önemli: niyetler mi yoksa metinler mi?

Genellikle kararlı bir senaryo daha önemlidir: anlaşılır kısa yanıtlar + fallback + doğru sonlandırma. Niyetler yinelemeli olarak iyileştirilebilir, ancak «bozulan» bir diyalog çoğu zaman reddedilmenin ve kötü yorumların nedenidir.