Použití SQL MCP Serveru s místními modely

Important

Server MCP (SQL Model Context Protocol) je k dispozici v Tvůrci rozhraní Data API verze 1.7. Nejnovější možnosti a opravy chyb najdete ve verzi 2.0 Preview.

Sql Model Context Protocol (MCP) Server funguje s libovolným klientem kompatibilním s MCP, nejen se službami AI hostovanými v cloudu. Pokud vaše prostředí omezuje přístup k cloudovému rozsáhlému jazykovému modelu (LLM), což je běžné ve zdravotnictví, obraně, financích, energii a námořních odvětvích, můžete propojit místní model obsluhovaný prostřednictvím Ollama nebo podobných nástrojů. Tato příručka se zabývá nastavením, konfigurací metadat polí a vzory promptů, které zajišťují spolehlivost malých lokálních modelů.

Předpoklady

• Nástroj příkazového řádku Data API Builder nainstalovaný a nakonfigurovaný s alespoň jednou entitou Nainstalujte rozhraní příkazového řádku.
• Ollama s modelem, který podporuje volání nástrojů (například qwen3:8b, llama3.1:8b).
• Python 3.10+ s balíčky mcp a ollama.
• Spuštěná instance SQL Server s daty.

Krok 1: Konfigurace metadat polí

Metadata polí jsou nejdůležitějším krokem konfigurace pro přesnost místního modelu. Bez názvů a popisů polí agenti vidí jen názvy entit a názvy sloupců odhadují nesprávně.

Warning

Přeskočení tohoto kroku vytvoří server MCP, který technicky funguje, ale je funkčně nepoužitelný v jakémkoli modelu, který čte odpovědi nástroje. Model nemá žádné informace o vašich sloupcích.

Přidejte entitu s popisem a přidejte popisy polí, které obsahují platné hodnoty pro omezené sloupce:

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"

Kompletní referenční informace k rozhraní příkazového řádku a osvědčené postupy, včetně omezených hodnot, popisů parametrů a vzorů skriptování, najdete v tématu Přidání popisů k entitám.

Note

Nástroj příkazového řádku dab update považuje čárky za oddělovače argumentů. Pokud váš popis obsahuje čárky, upravte místo toho přímo dab-config.json.

Krok 2: Spuštění SQL MCP Serveru

dab start

SQL MCP Server ve výchozím nastavení naslouchá na http://localhost:5000/mcp pomocí streamovatelného HTTP přenosu. Každý klient, který implementuje protokol MCP, se může připojit k tomuto koncovému bodu.

Krok 3: Připojení místního modelu

Vytvořte klienta MCP, který připojuje váš model Ollama k SQL MCP Serveru. Následující příklad Python používá MCP Python SDK a balíček ollama.

Nainstalujte závislosti

pip install mcp ollama

Minimální Python postroj

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?"))

Tento modul zpracovává celý cyklus: předběžné vložení schématu, zjišťování dostupných nástrojů, vícekolové volání nástrojů a extrakci konečné odpovědi. Upravte MODEL a MCP_URL pro své prostředí.

Předem vložit schéma při spuštění

Malé lokální modely (s méně než 14 miliardami parametrů) generují spolehlivější volání nástrojů, když jsou metadata schématu v systémovém promptu ještě předtím, než konverzace začne. Místo toho, abyste se během konverzace spoléhali na to, že model sám zavolá describe_entities, zavolejte ho při spuštění harnessu a vložte výsledek.

Proč je předvstřik důležitý

Přístup	Chování s malými modely
Dynamické zjišťování	Model se musí nejprve rozhodnout volat describe_entities , pak interpretovat výsledky a pak volat správný nástroj se správnými názvy polí. Několik bodů selhání
Předvstřik	Model okamžitě zobrazí názvy entit, názvy polí a popisy. Opravte volání nástrojů hned napoprvé.

Příklad s harnessem v předchozí části ukazuje tento vzorec. Funkce get_schema() volá describe_entities při spuštění jednou a naformátuje výsledek do systémové výzvy.

Tip

Větší cloudové modely (GPT-4o, Claude) obvykle během konverzace odhalí schéma i bez předběžného vložení. Tento přístup je nejpřínosnější pro modely s méně než 14 miliardami parametrů.

Omezte odpovědi modelu

Model může provést správné volání nástroje, načíst správná data a přesto vytvořit nesprávnou odpověď. Například model, kterému byla položena otázka „kolik produkčních serverů?“, může správně načíst 16 řádků a poté odpovědět 40řádkovým shrnutím pro vedení obsahujícím halucinované příklady místo čísla 16.

Přidejte do příkazového řádku systému explicitní záporná pravidla:

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.

Spolehlivost při volání nástrojů a ukázněnost odpovědí jsou různé problémy. DAB zajišťuje přesné načítání dat přes vrstvu nástroje. Vrstva pro práci s prompty určuje, jak model prezentuje výsledky.

Considerations

Téma	Podrobnosti
Hardware	Volání nástrojů funguje i na méně výkonném hardwaru. Model s parametrem 8B na uživatelském grafickém procesoru Nvidia GPU (8 GB video RAM) generuje užitečné výsledky. Počítejte s latencí v řádu desítek sekund na otázku, což je vhodné pro dávkové úlohy.
Batch vs. interactive	Malé modely jsou vhodné pro dávkové zpracování (výkonnostní přehledy, dotazy na inventář), kde je vyšší tolerance latence.
Dostupnost nástrojů	aggregate_records je k dispozici pouze ve verzi 2.0 Preview a novější. Ve verzi 1.7.x dotazy COUNT a agregační dotazy nutí model číst všechny odpovídající řádky. Podívejte se na dostupnost nástrojů podle verze.
Přeprava	Místní modely se připojují prostřednictvím streamovatelného protokolu HTTP do /mcp. Standardní přenos vstupu a výstupu (stdio) je alternativou pro nastavení s jedním procesem.
Autentizace	Pro místní vývoj použijte anonymous oprávnění. V produkčním prostředí nakonfigurujte ověřování odpovídající vašemu prostředí.

Související obsah

• Přidání popisů k entitám
• Nástroje pro manipulaci s daty
• Nasazení v prostředích s mezerami vzduchu
• Konfigurace ověřování
• Transport stdio