Menggunakan SQL MCP Server dengan model lokal

Important

Server Protokol Konteks Model SQL (MCP) tersedia di pembuat API Data versi 1.7 dan yang lebih baru. Untuk kemampuan terbaru dan perbaikan bug, gunakan rilis 2.0 terbaru.

Server SQL Model Context Protocol (MCP) berfungsi dengan klien yang kompatibel dengan MCP, bukan hanya layanan AI yang dihosting cloud. Jika lingkungan Anda membatasi akses model bahasa besar cloud (LLM) —umum dalam industri kesehatan, pertahanan, keuangan, energi, dan maritim—Anda dapat menghubungkan model lokal yang disajikan melalui Ollama atau alat serupa. Panduan ini mencakup pengaturan, konfigurasi metadata bidang, dan pola prompt yang membuat model lokal kecil dapat diandalkan.

Prasyarat

• CLI Data API Builder diinstal dan dikonfigurasi dengan setidaknya satu entitas. PasangCLI .
• Ollama dengan model yang mendukung panggilan alat (misalnya, qwen3:8b, llama3.1:8b).
• Python 3.10+ dengan paket mcp dan ollama.
• Instans SQL Server yang berjalan dengan data.

Langkah 1: Mengonfigurasi metadata bidang

Metadata bidang adalah langkah konfigurasi terpenting untuk akurasi model lokal. Tanpa nama dan deskripsi bidang, agen hanya melihat nama entitas dan menebak nama kolom dengan salah.

Warning

Melewati langkah ini menghasilkan server MCP yang secara teknis berfungsi tetapi secara fungsional tidak dapat digunakan oleh model apa pun yang membaca respons alat. Model tersebut tidak memiliki informasi tentang kolom Anda.

Tambahkan entitas Anda dengan deskripsi, lalu tambahkan deskripsi bidang yang menyertakan nilai yang valid untuk kolom yang dibatasi:

dab add ServerInventory \
  --source dbo.ServerInventory \
  --permissions "anonymous:read" \
  --description "SQL Server instance inventory with version, environment, and sizing data"

dab update ServerInventory \
  --fields.name InstanceName --fields.primary-key true \
  --fields.description "SQL Server instance name (e.g., YOURSERVER01)"

dab update ServerInventory \
  --fields.name Environment \
  --fields.description "Deployment environment. Valid values: Prod, Dev, Test, UAT"

Untuk referensi CLI lengkap dan praktik terbaik—termasuk nilai yang dibatasi, deskripsi parameter, dan pola pembuatan skrip—lihat Menambahkan deskripsi ke entitas.

Note

dab update CLI memperlakukan koma sebagai pemisah argumen. Jika deskripsi Anda berisi koma, edit dab-config.json langsung sebagai gantinya.

Langkah 2: Mulai SQL MCP Server

dab start

SQL MCP Server mendengarkan pada http://localhost:5000/mcp menggunakan transport HTTP streaming secara default. Setiap klien yang mengimplementasikan protokol MCP dapat terhubung ke titik akhir ini.

Langkah 3: Sambungkan model lokal Anda

Bangun klien MCP yang menghubungkan model Ollama Anda ke SQL MCP Server. Contoh Python berikut menggunakan MCP Python SDK dan paket ollama.

Pasang dependensi

pip install mcp ollama

Harness Python minimal

import asyncio
import json
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
import ollama

MCP_URL = "http://localhost:5000/mcp"
MODEL = "qwen3:8b"

async def get_schema(session: ClientSession) -> str:
    """Call describe_entities and format results for the system prompt."""
    result = await session.call_tool("describe_entities", arguments={})
    entities = json.loads(result.content[0].text)
    lines = []
    for entity in entities.get("entities", []):
        fields = ", ".join(
            f"{f['name']} ({f.get('description', 'no description')})"
            for f in entity.get("fields", [])
        )
        lines.append(f"- {entity['name']}: {entity.get('description', '')}")
        if fields:
            lines.append(f"  Fields: {fields}")
    return "\n".join(lines)

async def run(user_question: str):
    async with streamable_http_client(MCP_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Preinject schema into the system prompt
            schema_text = await get_schema(session)
            system_prompt = f"""You query a SQL database through MCP tools.

Available entities:
{schema_text}

Rules:
- Use the exact field names shown above.
- Answer count questions with the count only.
- Do not produce summaries unless asked.
- Do not invent example data. Only return data from tool responses.
- If no results, say "No results found" and stop.
"""
            # Get available tools for Ollama
            tools_result = await session.list_tools()
            ollama_tools = [
                {
                    "type": "function",
                    "function": {
                        "name": t.name,
                        "description": t.description or "",
                        "parameters": t.inputSchema,
                    },
                }
                for t in tools_result.tools
            ]

            messages = [
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_question},
            ]

            # Chat loop: let the model call tools until it produces a final answer
            while True:
                response = ollama.chat(
                    model=MODEL, messages=messages, tools=ollama_tools
                )
                msg = response["message"]
                messages.append(msg)

                if not msg.get("tool_calls"):
                    print(msg["content"])
                    break

                for tc in msg["tool_calls"]:
                    result = await session.call_tool(
                        tc["function"]["name"],
                        arguments=tc["function"]["arguments"],
                    )
                    messages.append(
                        {
                            "role": "tool",
                            "content": result.content[0].text,
                        }
                    )

asyncio.run(run("How many SQL 2019 servers are in production?"))

Harness ini menangani siklus penuh: prainjeksi skema, penemuan alat, panggilan alat multi-giliran, dan ekstraksi jawaban akhir. Sesuaikan MODEL dan MCP_URL untuk lingkungan Anda.

Prasuntik skema saat memulai

Model lokal kecil (di bawah parameter 14B) menghasilkan panggilan alat yang lebih andal ketika metadata skema berada di prompt sistem sebelum percakapan dimulai. Alih-alih mengandalkan model untuk memanggil describe_entities sendiri selama percakapan, panggil di harness startup dan masukkan hasilnya.

Mengapa pra-injeksi penting

Approach	Perilaku dengan model kecil
Penemuan dinamis	Model harus memutuskan untuk memanggil describe_entities terlebih dahulu, lalu menginterpretasikan hasil, lalu memanggil alat yang tepat dengan nama bidang yang benar. Beberapa titik kegagalan.
Preinjeksi	Model langsung melihat nama entitas, nama kolom, dan deskripsi. Lakukan pemanggilan alat dengan benar pada percobaan pertama.

Contoh harness di bagian sebelumnya menunjukkan pola ini. Fungsi get_schema() memanggil describe_entities sekali pada saat startup dan memformat hasilnya ke dalam prompt sistem.

Tip

Model cloud yang lebih besar (GPT-4o, Claude) biasanya dapat mengenali skema selama percakapan tanpa preinjeksi. Pola ini paling berharga untuk model di bawah parameter 14B.

Membatasi respons model

Sebuah model dapat melakukan pemanggilan alat yang benar, mengambil data yang tepat, dan namun tetap menghasilkan jawaban yang salah. Misalnya, model yang ditanya "ada berapa server produksi?" mungkin mengambil 16 baris dengan benar, lalu menjawab dengan ringkasan eksekutif sepanjang 40 baris yang berisi contoh yang dihalusinasikan alih-alih memberikan angka 16.

Tambahkan aturan negatif eksplisit ke prompt sistem Anda:

Rules:
- Answer count questions with the count only.
- Do not produce summaries unless the user asks for one.
- Do not invent example data. Only return data from tool responses.
- If a tool returns no results, say "No results found" and stop.

Keakuratan panggilan alat dan disiplin jawaban adalah masalah yang berbeda. DAB memastikan pengambilan data yang akurat melalui lapisan alat. Prompt harness Anda mengontrol bagaimana model menyajikan hasil.

Considerations

Topic	Rincian
Perangkat Keras	Pemanggilan alat dapat berjalan pada perangkat keras sederhana. Model parameter 8B pada GPU Nvidia konsumen (RAM video 8 GB) menghasilkan hasil yang berguna. Perkirakan latensi dalam kisaran puluhan detik per pertanyaan, sehingga cocok untuk beban kerja batch.
Batch vs. interaktif	Model kecil sangat cocok untuk pemrosesan batch (laporan performa, kueri inventaris) di mana toleransi latensi lebih tinggi.
Ketersediaan alat	Alat aggregate_records ini hanya tersedia di versi 2.0 dan yang lebih baru. Pada versi 1.7.x, kueri hitungan dan agregasi memaksa model untuk membaca semua baris yang cocok. Lihat ketersediaan alat menurut versi.
Transportasi	Model lokal terhubung ke /mcp melalui HTTP streaming. transpor input/output standar (stdio) adalah alternatif untuk konfigurasi proses tunggal.
Authentication	Untuk pengembangan lokal, gunakan izin anonymous. Untuk produksi, konfigurasikan autentikasi yang sesuai dengan lingkungan Anda.

Konten terkait

• Menambahkan deskripsi ke entitas
• Alat manipulasi data
• Terapkan di lingkungan terisolasi
• Mengonfigurasi autentikasi
• Transport Stdio