Niyet asistanı nasıl çalışır

Bu sayfa Cluster ERP'nin niyet asistanını açıklar. src/cluster_erp/ai/ içindeki motor (intent_engine.py, tokenizer.py, vectorizer.py ile intent_corpus_en.json ve intent_corpus_tr.json derlemleri) yazılan bir isteği bir API niyetiyle eşler. src/cluster_erp/server/routes/chat.py sohbet ucu motoru web uygulaması için sarar: sohbet ifadelerini işler, izinleri denetler, eşleşen ucu çağırır ve yanıtları döndürür. Ekranlar asistan ve sohbet ekranları ile masaüstü sohbet bileşeni sayfalarında anlatılır.

Kısaca¶

• Motor yerel bir metin sınıflandırıcıdır: Türkçe kök bulmalı belirteçleme, kelime ve karakter özellikleri, TF-IDF vektörleri ve örnek cümlelere kosinüs benzerliği (src/cluster_erp/ai/tokenizer.py:400-438, src/cluster_erp/ai/vectorizer.py:7-52).
• Bir niyet bir modülü, bir HTTP yöntemini, bir API yolunu ve bir açıklamayı adlandırır (src/cluster_erp/ai/intent_engine.py:14-24).
• Uç yalnızca, istemcinin kurulu olarak bildirdiği modüller içinde, çağıranın uç iznine sahip olduğu niyetleri sunar (src/cluster_erp/server/routes/chat.py:1158-1177, src/cluster_erp/server/routes/chat.py:1253-1265).
• Okumalar eşleşen liste ucunu çağıranın kendi belirteciyle süreç içinde çalıştırır; oluşturma niyetleri bir görev kartı döndürür; güncelleme ve silme niyetleri işlem yapmak yerine kayda yönlendirir (src/cluster_erp/server/routes/chat.py:1055-1066, src/cluster_erp/server/routes/chat.py:1436-1466).

Nasıl çalışır¶

İstek yolu¶

flowchart TD
 A["POST /api/v1/chat/message: text, action_context, allowed_modules"] --> P["require_permission dashboard.read"]
 P --> AC{"action_context var mı"}
 AC -->|evet| HA["_handle_action devam isteği"]
 AC -->|hayır| ST{"sohbet ifadesi"}
 ST -->|evet| SR["sabit selamlama veya yardım yanıtı"]
 ST -->|hayır| SP["_try_split_intents"]
 SP --> RE["IntentEngine.recognize ilk 5"]
 RE --> F["_intent_allowed: modül kapsamı ve izin kodu"]
 F -->|hiç kalmadı| FB["_scope_fallback"]
 F --> C{"güven 0.60 altında mı"}
 C -->|evet| SUG["bunu mu demek istediniz, ilk 3"]
 C -->|hayır| K{"niyet türü"}
 K -->|liste veya okuma| G["çağıran belirteciyle süreç içinde _api_get"]
 K -->|oluşturma| T["metadata'dan görev kartı"]
 K -->|güncelleme veya silme| N["kayda yönlendirme"]

Düz anlatımla:

1. Uç dashboard.read ister ve çağıranın izin kodlarını yükler (src/cluster_erp/server/routes/chat.py:1191-1200).
2. Metinde Türkçe harfler veya yaygın Türkçe komut kelimeleri varsa dil Türkçe, aksi halde İngilizcedir (src/cluster_erp/server/routes/chat.py:999-1040).
3. Bir aksiyon düğmesinden gelen devam isteği _handle_action ucuna gider. Selamlamalar ve yardım istekleri sabit bir yanıt alır (src/cluster_erp/server/routes/chat.py:1209-1218, src/cluster_erp/server/routes/chat.py:537-647).
4. Birden çok istek içeren metin bölünür ve her parça sırayla işlenir (src/cluster_erp/server/routes/chat.py:1223-1239, src/cluster_erp/server/routes/chat.py:664-717).
5. IntentEngine.recognize en fazla beş aday döndürür. Motor süreç başına bir kez oluşturulur ve yüklenir (src/cluster_erp/server/routes/chat.py:24-35, src/cluster_erp/server/routes/chat.py:1253).
6. Çağıranın erişemeyeceği uçlara ait adaylar, hiçbir şey gösterilmeden önce çıkarılır. Aday kalmazsa yanıt bilinmeyen bir istekle aynıdır (src/cluster_erp/server/routes/chat.py:1255-1265, src/cluster_erp/server/routes/chat.py:1179-1185).
7. 0,60 güvenin altında uç ilk üç adayı öneri olarak listeler (src/cluster_erp/server/routes/chat.py:1270-1279).
8. Liste veya okuma niyetinde uç metinden süzgeçleri, zaman sırasını ve bir arama terimini kurar, ucu çağıranın Authorization başlığıyla bir ASGI taşıması üzerinden süreç içinde çağırır ve satırları metadata'daki liste sütunlarıyla biçimlendirir (src/cluster_erp/server/routes/chat.py:1282-1433, src/cluster_erp/server/routes/chat.py:1055-1066).
9. Oluşturma niyetinde varlığın form metadata'sından alanlarla bir görev kartı kurar; güncelleme ve silme niyetlerinde kullanıcıdan kaydı açmasını ister (src/cluster_erp/server/routes/chat.py:1436-1466, src/cluster_erp/server/routes/chat.py:1552).

Eşleştirme¶

IntentEngine.load her derlemi okur, her örnekten özellik çıkarır, dil başına bir TF-IDF vektörleştirici eğitir ve örnek vektörlerini, bir açıklama vektörünü ve niyet kimliğinin düzgünleştirilmiş parçalarını saklar (src/cluster_erp/ai/intent_engine.py:364-418).

Bir aday için varsayılan eşik 0,05, varsayılan sonuç sayısı 5'tir (src/cluster_erp/ai/intent_engine.py:420-426).

Derlemler¶

Her derlem version, description, total_intents ve intents alanlarını içeren bir JSON dosyasıdır. Bir niyetin id, module, method, path, description ve examples alanları vardır (src/cluster_erp/ai/intent_corpus_en.json, src/cluster_erp/ai/intent_corpus_tr.json). İki dosyanın JSON yüklemesiyle sayıldı: her dilde 347 niyet, 1553 İngilizce örnek ve 1168 Türkçe örnek. Niyetler 12 hedefi kapsar: auth, crm, currencies, design_engineering, documents, owned_organisations, parties, products_and_services, projects, quotations, sales_orders ve server.

Neden böyle kurulmuş¶

• Uç yorumu, asistanın yalnızca çağıranın erişebileceklerini bildiğini; böylece kapsam dışı niyetlerin açıklama, öneri veya form sızdıramayacağını belirtir (src/cluster_erp/server/routes/chat.py:1255-1258).
• ChatRequest.allowed_modules yalnızca asistanın sunduklarını daraltır; izinler her zaman çağıranın belirtecinden uygulanır (src/cluster_erp/server/routes/chat.py:1069-1077).
• Bir niyetin izin kodu, elle tutulan bir listeden değil, metadata'dan {entity_key}.{action} biçiminde türetilir (src/cluster_erp/server/routes/chat.py:1120-1156).

Kurallar ve sınırlar¶

• Metin en fazla 2000 karakter; allowed_modules en fazla 200 girdidir (src/cluster_erp/server/routes/chat.py:1069-1077).
• Ucu metadata içinde çözülemeyen niyet reddedilir (src/cluster_erp/server/routes/chat.py:1158-1177).
• Asistan güncelleme veya silme aksiyonu çalıştırmaz (src/cluster_erp/server/routes/chat.py:1454-1466).
• Masaüstü istemcisi sohbet bileşeninde kendi IntentEngine nesnesini kurar (src/cluster_erp/desktop/widgets/chat/chat_widget.py:47, src/cluster_erp/desktop/widgets/chat/chat_widget.py:818).

Diğer parçalarla etkileşim¶

Sohbet ucu modüller dışındaki sunucu uçlarından biridir; bkz. paylaşılan sunucu uçları.

Sınırlar ve açık noktalar¶

• Derlemler 12 hedefi kapsar; fleet, intranet, inventory veya analytics gibi modüller için niyet iki derlemde de bulunamadı.
• Selamlamalar, yardım metni, öneriler ve geri dönüşler gibi yanıtlar uç içinde Türkçe veya İngilizce dizeler olarak kurulur (src/cluster_erp/server/routes/chat.py:537-647, src/cluster_erp/server/routes/chat.py:1179-1185, src/cluster_erp/server/routes/chat.py:1270-1276).

Tutarsızlıklar¶

Tanıtılan terimler¶

İlgili sayfalar¶

• Niyet asistanı bölümü
• Asistan ve sohbet ekranları
• Masaüstü sohbet bileşeni
• Roller ve izinler
• Metadata modeli

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.