İşlev çağrısıyla Postgres aracısını güvenli hale getirin (öğretici)

Modelin olduğu gibi çalışan SQL yazmasına asla izin vermeden, bir Postgres projesinde verilerle ilgili doğal dil sorularını yanıtlayan bir aracı oluşturacaksınız. Model, query_databaseadlı 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.

Bazı resmi kılavuzlar da dahil olmak üzere çoğu Postgres aracısı öğ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ün ayrıntılarını vermektedir: 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 (yalnızca SELECT, alt sorgu yok, on işlev yetkili, sınırlı LIMIT) geçirmeden önce SQL'e çeviren Aurabase NL2SQL motoru'dir.

Aurabase'in üç yerel LLM sağlayıcısı (OpenAI, Anthropic, Gemini), JSON Schema formatındaki 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
      },
    },
  },
]

Araç işleyicisi arka uçta çalışır, asla tarayıcıda çalışmaz. Tasarım gereği RLS'yi atlayan ve bu nedenle hiçbir zaman istemciye açıklanmaması gereken service_roleproje 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'in kendisi, NL2SQL yukarı akış tarafından halihazırda 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 }
}

Aurabase üç yerel LLM sağlayıcısını kullanıma sunuyor ancak /chat uç noktası henüz bir tools parametresini veya toolrolünü aktarmıyor. ChatOptions yalnızca temperature, max_tokens ve modeltaşır ve kabul edilen roller system, user ve assistant (llm/mod.rs ve handlers/chat.rsiç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.

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
}

Aracıyı LangChain veya Azure AI Agent gibi bir hizmetle düzenlerseniz prensip aynı kalır: çerçevede bildirilen araç aynı kalmalı query_database, asla ham bir SQL yürütücüsü olmamalıdır. Karşılaştırma ayrıntılarımız LangChain ve LlamaIndex'in Postgres'te gerçek değer sağladığı ve özellikle karmaşıklık kattığı noktalardır: LangChain veya LlamaIndex'li Postgres aracıları.

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.

• service_role anahtarı 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çin aura.db.sql() üzerinde etkin kalır.
• service_role tasarı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'ye saygı duyan klasik PostgREST uç noktalarına geri dönün. çok kiracılı RLS yalıtımıkonusuna bakın.
• Her araç çağrısını günlüğe kaydedin (sorulan soru, SQL'in doğrulanması, satır sayısı): Bir sorunun beklenmeyen bir sonuç üretmesi durumunda kullanılabilen tek iz budur.
• Aurabase'in oran 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.

query_database aracı, NL2SQL doğrulayıcısı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 sorunun (“hiç sipariş vermemiş müşteriler”) yeniden formüle edilmesi veya NL2SQL'e zorlanmak yerine ikinci bir özel araç tarafından işlenmesi gerekir.

Bugün Aurabase /chat proxy'sinde 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 birden fazla aracı zincirlemesi gerekiyorsa (örneğin, veritabanı ve belgesel RAG), iki çağrıyı düzenleyen sizin arka ucunuzdur.

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ı temsilci, Aurabase'in yerel RAG'sine (pgvector, HNSW arama) bağlı ikinci bir aracı kullanıma sunabilir. İki yetenek ve bunların eklemlenmesi Postgres'te Yerel Yapay Zekasayfasında ayrıntılı olarak açıklanmıştır.