Ana içeriğe geç

Makinist

Makinist, Compass modülünün SQL Sorgu Yazma ekranında çalışan yapay zeka asistanıdır. Seçili veri kaynağındaki tabloları bağlam olarak alır, doğal dilde yazılan istekleri Langflow flow'una iletir ve çalıştırılabilir SQL olarak geri döner. Üretilen SQL bloğu tek tıkla editöre aktarılabilir.

Desteklenen Veri Kaynağı Tipleri

Makinist sohbeti, Compass'ın SQL grubuna giren veri kaynaklarında (PostgreSQL, MSSQL, MySQL) açılır. MQTT, REST API ve Excel sorgu ekranlarında bu özellik bulunmaz; çünkü oradaki sorgular SQL formatında değildir.

Ön Koşul

Makinist, yalnızca SQL tipi veri kaynaklarında (PostgreSQL, MSSQL, MySQL) çalışır. Bu veri kaynakları önce Port modülünde tanımlanmış olmalıdır.

SQL sorgularında ${değişken} syntax'ıyla Global Variables kullanabilirsiniz. Dinamik kullanıcı parametreleri için → Compass Parametreleri

1. Sohbeti Açma

Compass'ta yeni bir SQL sorgusu yazarken sayfanın üst aksiyon bölgesinde bulunan Yapay Zeka ile Yaz butonuna tıklayın.

UI Öğesi Davranış
Yapay Zeka ile Yaz butonu Sohbet panelini açar; başlık Makinist olarak değişir, ikon palette → smart_toy
Sohbeti Kapat butonu Aynı buton açıkken Sohbeti Kapat etiketi alır; sohbeti gizler
Yeni Oturum Yeni username_DatasourceName_Mon_HH:mm:ss ID'si oluşturur ve seçili oturum yapar

Sohbet açıldığında ekran iki bölüme ayrılır: solda mesaj geçmişi ve input alanı, üstte oturum seçici dropdown'u görünür.

2. Tablo Seçimi (Bağlam Verme)

Makinist'in doğru SQL üretebilmesi için sorguyu yazacağı tabloları bilmesi gerekir. Bu nedenle her mesaj göndermeden önce en az bir tablo seçilmiş olmalıdır.

Tablo Seçici Davranışı

  1. Input satırının solundaki table_chart ikonlu butona tıklayın.
  2. Açılan modal sheet'te veri kaynağındaki tüm tablolar listelenir (Compass'ın tablesResponse listesinden alınır).
  3. Bir veya birden fazla tabloyu seçip OK ile kapatın.
  4. Seçilen tablolar input'un üstünde chip olarak görünür; chip'in x ikonu ile tek tek kaldırılabilir.
Durum Sonuç
Hiç tablo seçilmemiş Mesaj gönderilemez; "Lütfen en az bir tablo seçin ve bir mesaj yazın." uyarısı çıkar
Tablo seçili ama mesaj boş Aynı uyarı çıkar
Tablo seçili ve mesaj yazılı İstek ask_agent action'ı ile Langflow'a gönderilir

Az Tablo, Net Sorgu

Aynı anda 10+ tablo seçmek modelin doğru tabloyu bulmasını zorlaştırır. Sorgu için gerekli olan minimum tablo setini seçmek genelde daha doğru SQL üretir.

3. Mesaj Gönderildiğinde Ne Olur?

Send butonuna bastığınızda Makinist Langflow API'ye şu paketi gönderir:

Paket Bileşeni Kaynağı
prompt Input alanına yazdığınız metin
id compassController.selectedDataSourceId.value (seçili veri kaynağı ID'si)
table_name Seçilen tablo isimleri listesi
ds_type compassController.selectedDataSourceType.value (postgresql / mssql / mysql)
session_id Aktif oturum ID'si 
flowchart LR
    A[Tablo seçimi] --> P[Prompt]
    P --> Q[ask_agent action]
    Q --> L[Langflow API]
    L --> R[SQL kod bloğu döner]
    R --> M[Markdown render]
    M --> U[SQL Kullan butonu]

Yanıt gelene kadar mesaj listesinde geçici typing... balonu görünür. Yanıt geldiğinde kaldırılır ve gerçek mesaj eklenir.

İstek İptali

Yanıt beklerken Send butonu stop ikonuna döner. Tıklandığında:

  • HTTP istemcisi _httpClient?.close() ile kapatılır.
  • typing... balonu kaldırılır.
  • Yeni mesaj göndermek serbest hâle gelir.

4. Yanıt Üzerinde Kod Blokları

Makinist mesajları Markdown olarak render edilir. Kod blokları (``` ile sarılı) ekstra başlık çubuğuyla görünür:

Buton Davranış
Kopyala Kod bloğunun tamamını panoya kopyalar; "Panoya kopyalandı" SnackBar'ı gösterir
SQL Kullan (Sadece sql dilli kod bloklarında görünür) — compassController.codeSQLController.text alanına aktarır, parametreleri parse eder ve sohbeti otomatik kapatır 
flowchart LR
    A[AI yanıtı] --> B{Kod bloğu var mı?}
    B -->|Evet, sql| C[SQL Kullan + Kopyala]
    B -->|Evet, diğer dil| D[Sadece Kopyala]
    B -->|Hayır| E[Düz Markdown]

Sorguyu Kullanmadan Önce

SQL Kullan butonu üretilen sorguyu olduğu gibi editöre yapıştırır; Compass otomatik çalıştırmaz. Önce manuel olarak gözden geçirip, sonra Run ile test etmeniz önerilir.

5. Oturum Yönetimi

Makinist, kullanıcı bazında veri kaynağı + zaman damgalı oturumlar tutar.

Oturum İsimlendirme Formatı

{username}_{DatasourceName}_{Mon}_{HH:mm:ss}

Örnek: furkan_PrdLineDB_Oct_14:32:08

Bileşen Kaynak
username GetStorage().read('username')
DatasourceName Seçili veri kaynağının adı (boşluklar kaldırılarak)
Mon İngilizce 3 harfli ay (Jan, Oct, vb.)
HH:mm:ss Yerel saat

Oturum Geçişi

Sohbet üst panelindeki dropdown ile geçmiş oturumlara geçebilirsiniz. Yeni oturum açıldığında listenin başına eklenir; mesaj göndermeden başka oturuma geçerseniz boş oturum otomatik temizlenir.

Oturum Silme

Aktif oturumda en az bir mesaj varsa silme butonu görünür. Sildiğinizde:

  1. Langflow'da delete_session action'ı çalışır.
  2. Yeni boş bir oturum üretilip aktif yapılır.
  3. Mesaj geçmişi temizlenir.
  4. Listeden silinen oturum kaldırılır.

6. Doğru Soru Yazma İpuçları

Soru Tipi Örnek
Filtre + agregasyon "Son 7 günde her hat için toplam üretim adedini ver"
JOIN "Sipariş tablosunu müşteri tablosuyla birleştirip son 30 günün ciroyu müşteri bazında özetle"
Tarih bazlı "Bu ayın saatlik ortalama duruş süresini hesapla"
Top-N "En çok hata üreten 5 makineyi listele"
Pivot benzeri "Vardiyaya göre üretim adedini sütunlara aç"

Schema Bilgisi Vermek

Makinist tabloların kolon isimlerini Langflow flow'una sağlanan metadata üzerinden bilebilir; ancak iş kuralları (örn. "duruş = status_code = 'D'") modele iletilmediği için cevaplar yanlış olabilir. Bu gibi kuralları prompt içinde açıkça yazın:

"Duruşları status_code = 'D' olarak kabul et. Son 24 saatteki toplam duruş süresini makine bazında listele."

7. Geçmişin Kalıcılığı

Sohbet geçmişi Langflow tarafında oturum ID'si üzerinden saklanır. Tarayıcı kapatılıp yeniden açıldığında:

  1. getSessions ile kullanıcı için oturum listesi tekrar çekilir.
  2. Bir oturum seçildiğinde getSession ile mesaj geçmişi yüklenir.
  3. Mesajlar User ve Makinist rollerine ayrılarak chat'e basılır.

User mesajları DB'de JSON olarak saklanır ({"prompt": "..."}), UI bunları decode ederek gösterir.

Veri Kaynağı Uyumsuzluğu

Eğer aktif veri kaynağı, oturumun oluşturulduğu kaynağa uymuyorsa input alanı devre dışı bırakılır ("Seçili veri kaynağı ile sohbet geçmişi uyumlu olmadığı için giriş devre dışı."). Yeni bir oturum başlatmanız gerekir.

8. Sınırlamalar

  • Sadece SQL gruplu veri kaynaklarında (PostgreSQL, MSSQL, MySQL) görünür.
  • Yanıt kalitesi Langflow flow yapılandırmasına ve metadata zenginliğine bağlıdır.
  • Çok büyük tablolar için karmaşık JOIN'lerde model schema'yı yanlış yorumlayabilir.
  • Servis erişilemez olduğunda istek hata döner; sohbet boş kalır.
  • Aynı anda tek istek desteklenir; cevap beklerken yeni mesaj göndermek için iptal etmeniz gerekir.

9. Sorun Giderme

Belirti Olası Neden Çözüm
Buton tepki vermiyor pirivision-langflow-api servisi ayakta değil Sistem yöneticinizle iletişime geçin
"Lütfen en az bir tablo seçin..." Tablo seçilmedi veya prompt boş Tablo simgesinden tablo seçin, mesaj yazın
Yanıt sürekli typing... İstek askıda kalmış olabilir Stop butonuyla iptal edin, tekrar deneyin
Üretilen SQL hata veriyor Schema yanlış yorumlanmış Tablo seçimini daraltın veya prompt'u netleştirin
Geçmiş yüklenmiyor get_session_history action'ı 4xx/5xx dönmüş Sistem yöneticinizle iletişime geçin

10. Sonraki Adım

→ CaptainAI — Horizon Board Asistanı → AI Ekosistemi — Genel Bakış → Ekosistem