Bu öğretici, modele sunulan aracın hiçbir zaman rastgele SQL yürütmediği, işlev çağırma özelliğine sahip bir aracı oluşturur. Aurabase kodunda zaten doğrulanmış olan iki mekanizmayı birleştirir: NL2SQL doğrulayıcı ve salt okunur bir Postgres işlemi,yerel yapay zekanın iki tuğlasıarka ucuna entegre edilmiştir. Önkoşullar: bir Aurabase projesi, service_roleanahtarı ve üç yerel LLM sağlayıcısından (OpenAI, Anthropic, Gemini) birinde hesap.
Temeller
- Gerçek risk, kendisini çağıran fonksiyon değil, modele maruz kalan araçtır: ham bir
execute_sql(query)ona tam SQL erişimi sağlar. - Güvenli mimari, doğrudan yürütme yerine sözdizimi ağacı doğrulayıcısına (yalnızca SELECT, sınırlı LIMIT, yalıtılmış şema) yetki veren bir
query_database(question)aracını kullanıma sunar. - Aurabase bu doğrulayıcıyı yerel olarak kullanıma sunar (
/nl2sql): aracın bir uygulaması olarak yeniden kullanılması, SQL doğrulamasını kendinizin yeniden kodlaması zorunluluğunu ortadan kaldırır. - Taahhüt edilen SQL daha sonra basit bir metin filtresi değil, gerçek bir salt okunur Postgres işlemi olan
readOnly: truemodundaaura.db.sql()aracılığıyla yürütülür. - Aurabase'nin yerel
/chatuç noktası henüz birtoolrolünü veya birtoolsparametresini (kodda doğrulanmıştır) kabul etmiyor: aracı döngüsü şu anda Aurabase proxy aracılığıyla değil, LLM sağlayıcısının SDK'sı aracılığıyla çalışıyor. service_roleanahtarı, tasarım gereği RLS anahtarını atlar: arka uçtan asla ayrılmamalıdır ve aracı, kimliği doğrulanmış tipik bir kullanıcıdan daha geniş bir erişimi devralır.
Ne inşa edeceksin
Modelin olduğu gibi çalışan SQL yazmasına izin vermeden, bir Postgres projesindeki verilerle ilgili doğal dil sorularını yanıtlayan bir aracı oluşturacaksınız. Model, query_database adlı bir aracı çağırır, bu araç soruyu NL2SQL aracılığıyla doğrulanan SQL'e çevirir, ardından bu salt okunur SQL'i çalıştırır ve cevabını formüle etmesi için satırları modele döndürür.
Bu eğitimde, sunucu tarafında @aurabase/aurabase-js JavaScript SDK'sı (hiçbir zaman tarayıcı tarafında değil, service_role anahtarı istemciye gösterilmemelidir) ve aracı döngüsü için API çağıran OpenAI işlevi kullanılır. Aynı prensip Anthropic veya Gemini SDK'sı için de geçerlidir.
"Bu SQL'i çalıştır" aracı neden tehlikelidir?
Bazı resmi kılavuzlar da dahil olmak üzere çoğu Postgres aracı öğreticisi, tek bir araç tanımlar: bir SQL dizesini argüman olarak alan ve onu olduğu gibi yürüten bir execute_sql işlevi. Model, kullanıcının sorusuna ve bağlamda kendisine verilen şemaya dayanarak bu dizeyi kendisi yazar.
{
"name": "execute_sql",
"parameters": {
"query": { "type": "string" } // model doğrudan SQL'i yazar
}
}
Bu seçim, modele güvenilir bir şekilde yerine getiremeyeceği bir sorumluluk yükler. Sorunun içine anında yapılan bir enjeksiyon, aracın "meşru" bir sorgunun nasıl görünmesi gerektiğine dair hiçbir fikri olmadığı için, aracın ayrım gözetmeksizin yürüttüğü yıkıcı SQL üretebilir. Özel makalemiz bu saldırı vektörünü ayrıntılarıyla anlatıyor: NL2SQL'in SQL enjeksiyonuna karşı güvenliğinin sağlanması.
Bu eğitimde yerleşik olan alternatif, daha dar bir araç olan query_database(question)'yi ortaya çıkarır. Model artık SQL'i doğrudan yazamaz: yalnızca kendi araç çağrısında soru sorabilir. Bu soruyu sözdizimsel bir ağaç doğrulayıcıdan geçirmeden önce SQL'e çeviren, Aurabase NL2SQL motoru'dir (yalnız SELECT, alt sorgu yok, on işlev yetkili, sınırlı LIMIT).
Bir execute_sql(query: string) aracı, sistem isteminizin ne kadar iyi olduğuna bakılmaksızın modele tam SQL erişimi sağlar. Bir talimat ("yalnızca SELECT'leri çalıştırır"), modelin izleyebileceği, yanlış yorumlayabileceği veya kullanıcının sorusuna eklenen bir enjeksiyonla atlatıldığını görebileceği bir talimat olarak kalır.
Modele maruz kalan aracın şemasını tanımlayın
Aurabase'nin üç yerel LLM sağlayıcısı (OpenAI, Anthropic, Gemini), JSON Şema formatında bir araç tanımları tablosunu kabul eder. Bu aracı için tek bir araç yeterlidir: query_database, doğal dilde bir soru alır, başka hiçbir şey yapmaz. Model ne SQL şemasını ne de kendi başına doldurabileceği bir query alanını görüyor.
export const tools = [
{
type: 'function',
function: {
name: 'query_database',
description:
"Interroge les données du projet en langage naturel. N'accepte pas de SQL : posez une question.",
parameters: {
type: 'object',
properties: {
question: {
type: 'string',
description: 'Question en français sur les données du projet.'
},
},
required: ['question'],
additionalProperties: false
},
},
},
]
Aracı uygulayın: NL2SQL ve ardından salt okunur
Araç işleyicisi arka uçta çalışır, asla tarayıcıda çalışmaz. Tasarım gereği RLS'yi atlayan ve bu nedenle asla bir istemciye gösterilmemesi gereken service_role proje anahtarını taşır. Aurabase SDK'ya iki çağrı yapar.
İlk çağrı, soruyu aura.ai.nl2sql() aracılığıyla doğrulanan SQL'e çevirir: Yalnızca SELECT, LIMIT sınırlı, sistem kataloğuna erişim yok. İkincisi, aura.db.sql() aracılığıyla zaten doğrulanmış olan bu SQL'i readOnly: true seçeneğiyle çalıştırır: Postgres kendisi daha sonra, NL2SQL yukarı akış tarafından zaten uygulanan metinsel doğrulamadan bağımsız olarak bu işlemdeki herhangi bir yazmayı reddeder.
// İstemci service_role anahtarıyla başlatıldı, hiçbir zaman tarayıcı tarafında değil
import { aura } from '@/lib/aurabase'
export async function queryDatabase(question: string) {
const { data: validated, error } = await aura.ai.nl2sql(
question,
undefined,
{ limit: 50 },
)
if (error) return { error: error.message }
const { data: rows, error: execError } = await aura.db.sql(
validated.sql,
[],
{ readOnly: true },
)
if (execError) return { error: execError.message }
return { sql: validated.sql, rows }
}
readOnly: true gerçek bir salt okunur Postgres işlemini tetikler: motor yazmayı reddeder, istek metnine uygulanan bir filtre değildir. NL2SQL'nin yalnızca SELECT doğrulaması ile birleştirildiğinde, aracının iki bağımsız katmanı vardır: birinde kusur varsa diğeri hala geçerlidir.
Aracı döngüsü: tedarikçinin SDK tarafında çağrılan işlev
Aurabase üç yerel LLM sağlayıcısını kullanıma sunar, ancak /chat uç noktası henüz bir tools parametresini veya toolrolünü aktarmıyor. ChatOptions yalnızca temperature, max_tokens ve model taşır ve kabul edilen roller system, user ve assistant (llm/mod.rs ve handlers/chat.rs içinde doğrulanmıştır) ile sınırlıdır. Bu nedenle, işlev çağırma döngüsü bugün Aurabase proxy'si aracılığıyla değil, doğrudan sağlayıcının SDK'sı aracılığıyla çalışır.
Aurabase araç çağrılarını yerel olarak düzenlemediği sürece arka ucunuz döngüyü OpenAI, Anthropic veya Gemini SDK ile kendisi yönetmelidir. NL2SQL ve SQL yürütmesi, bu döngü içinde klasik Aurabase çağrıları olarak kalır.
import OpenAI from 'openai'
import { tools } from './lib/agent-tools'
import { queryDatabase } from './tools/query-database'
const openai = new OpenAI()
export async function askAgent(question: string) {
const messages = [{ role: 'user', content: question }]
const first = await openai.chat.completions.create({
model: 'gpt-4.1', messages, tools,
})
const call = first.choices[0].message.tool_calls?.[0]
if (!call) return first.choices[0].message.content
const args = JSON.parse(call.function.arguments)
const result = await queryDatabase(args.question)
const second = await openai.chat.completions.create({
model: 'gpt-4.1',
messages: [
...messages,
first.choices[0].message,
{ role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) },
],
})
return second.choices[0].message.content
}
The principle remains the same if you orchestrate the agent with LangChain or a service like Azure AI Agent: the tool declared in the framework must remain the same query_database, never a raw SQL executor. Our comparison details where LangChain and LlamaIndex provide real value on Postgres, and where they especially add complexity: Postgres agents with LangChain or LlamaIndex.
Gerçek bir soruyla test edin
Temsilciye gönderilen soru: "Bu ay kaç premium müşteri sipariş verdi?" ". Şablon, herhangi bir SQL görmeden veya yazmadan bu soruyla birlikte query_database öğesini çağırır. Araç tarafından tetiklenen iki dahili çağrının sonucu aşağıdadır.
{
"sql": "SELECT count(*) FROM orders WHERE customer_plan = 'premium' AND created_at >= date_trunc('month', now()) LIMIT 50",
"rows": [{ "count": 128 }]
}
Modelin nihai cevabı bir tahmine değil, bu gerçek satırlara dayanmaktadır. Araç sıfır satır döndürürse sayı halüsinasyonu olasılığı, doğrulanmış veriler olmadan yanıt veren bir modele göre önemli ölçüde daha az olur.
Üretime geçmeden önce temsilciyi emniyete alın
service_roleanahtarı hiçbir zaman arka ucunuzdan ayrılmaz: ne modele gönderilen istemde, ne bir günlükte, ne de istemci tarafı ortam değişkeninde.readOnly: true, projenizin uygulamanın başka bir yerinde yazılması gerekse bile, bu özel araç içinaura.db.sql()üzerinde etkin kalır.service_roletasarım gereği RLS'yi atlar. Aracının soruyu soran kullanıcıya bağlı olarak farklı yanıt vermesi gerekiyorsa, SQL'de açıkça filtre uygulayın veya RLS ile ilgilenen klasik PostgREST uç noktalarına geri dönün. çok kiracılı RLS izolasyon konusuna bakın.- Her araç çağrısını günlüğe kaydedin (sorulan soru, SQL tarafından doğrulanan, satır sayısı): Bir sorunun beklenmeyen bir sonuç üretmesi durumunda kullanılabilen tek iz budur.
- Aurabase'in hız sınırlaması ve aylık kotası,
/nl2sql'de proje başına zaten geçerlidir: konuşkan bir temsilci, yapay zeka bütçenizi sessizce aşamaz.
Dikkat edilmesi gereken mevcut sınırlar
query_database aracı, NL2SQL doğrulayıcının tüm sınırlamalarını devralır: alt sorgu yok, CTE/WITH yok, UNION yok ve on SQL işlevinden oluşan kapalı bir liste. Doğal olarak bir alt sorgu gerektiren bir soru ("hiç sipariş vermemiş müşteriler") yeniden formüle edilmeli veya NL2SQL'ye zorlanmak yerine ikinci bir özel araç tarafından işlenmelidir.
Bugün Aurabase /chat proxy içinde araç çağrılarının düzenlenmesi mevcut değildir: burada açıklanan aracı döngüsü, yönetilen bir hizmette değil, uygulama kodunuzda bulunur. Aracının birkaç aracı zincirlemesi gerekiyorsa (örneğin, veritabanı ve belgesel RAG), iki çağrıyı düzenleyen sizin arka ucunuzdur.
RAG ve işlev çağrısı birleştirildi
Bu eğitimde ilişkisel verilerle ilgili yapılandırılmış sorular ele alınmaktadır. Yapılandırılmamış içerikle (belgeler, biletler, notlar) ilgili sorular için aynı aracı, Aurabase'nin yerel RAG'sine (pgvector, HNSW arama) bağlı ikinci bir aracı kullanıma sunabilir. İki yetenek ve bunların eklemlenmesi Postgres üzerinde Yerel Yapay Zeka sayfasında ayrıntılı olarak açıklanmıştır.