Needle

Vytvořeno: 18.8.2026 | Aktualizováno: 18.08.2026 10:32

Needle je malý model určený pro tool/function calling a strukturovanou extrakci. Needle 2 není obecný chatovací model ani přímý ovladač zařízení; jeho úlohou je z textového vstupu vybrat přesné, předem povolené volání nástroje.

Aplikace předá modelu textový požadavek a deklarace dostupných nástrojů včetně jejich parametrů. Model vrátí JSON call; teprve aplikace musí parametry ověřit a následně provést akci přes API nebo jinou integrační vrstvu.

Tady je zjednodušená a bezpečná ukázka deklarace nástroje:

{
  "name": "set_light",
  "description": "Nastaví stav povoleného světla.",
  "parameters": {
    "type": "object",
    "properties": {
      "entity_id": {
        "type": "string",
        "enum": ["light.pracovna"]
      },
      "state": {
        "type": "string",
        "enum": ["on", "off"]
      }
    },
    "required": ["entity_id", "state"]
  }
}

Pro požadavek „rozsviť světlo v pracovně“ může model vrátit například:

{
  "name": "set_light",
  "arguments": {
    "entity_id": "light.pracovna",
    "state": "on"
  }
}

JSON výstup není oprávnění k provedení akce. Integrační vrstva musí kontrolovat, že nástroj, entita i hodnoty jsou povolené, a až potom zavolat cílové API.

Jednou z možných architektur hlasového ovládání je tento řetězec:

1. STT převede řeč na text; podle zvoleného řešení může předcházet překlad do angličtiny.
2. Needle z textu a omezeného katalogu schémat vybere strukturované volání.
3. Validovaná integrační vrstva zkontroluje oprávnění, parametry a kontext.
4. Vrstva provede povolenou akci v Home Assistantu nebo přes jiné API.

Nejde o hotové smart-home řešení. Needle v této architektuře pouze klasifikuje záměr a vytváří návrh volání; stav zařízení ani samotné vykonání akce musí řešit okolní aplikace.

Modelu není vhodné při každém běhu předávat kompletní dokumentaci ani široký RAG kontext. Lepší je předat krátké a přesné deklarace právě povolených nástrojů, entit a parametrů. Aktuální stav se má získávat explicitními nástroji, například nástrojem pro čtení stavu, ne odhadovat z dokumentace nebo konverzace.

Rozhraní nemá obsahovat všemocný nástroj typu „zavolej libovolnou službu“. Omezený katalog konkrétních akcí zmenšuje prostor pro chybu a dovoluje aplikaci jednodušeji vynucovat autorizaci a validaci.

Fine-tuning Needle používá LoRA pro naučení vzorů „příkaz → přesné volání nástroje a parametry“. Nemá sloužit k „zapečení“ dokumentace, která se může měnit. Trénovací data mohou být v JSONL a mají obsahovat také off-topic příklady, aby model poznal požadavky mimo podporovaný katalog; výsledný model se exportuje do souboru .cact.

Při tomto postupu se nemění tokenizer ani confidence head. Je proto potřeba oddělit učení formátu a mapování příkazů od znalostí, které se mění za běhu a patří do aplikace nebo explicitních nástrojů.

Modelová karta Needle 2 uvádí anglické ukázky a základní dokumentaci. Pro češtinu lze zvážit fine-tuning na vlastních příkazech. Dokumentace fine-tuningu u španělštiny upozorňuje na vyšší počet tokenů a nespolehlivě kalibrovanou confidence; fine-tuned model vrací confidence jako None. Tyto vlastnosti nelze nahradit odhadem — je nutné reálné testování a bezpečnostní kontroly v aplikaci.

Další omezení jsou posuvné kontextové okno o 256 tokenech, omezení daná tool callingem a schématy a skutečnost, že nejde o model pro obecnou konverzaci. Rozumný další krok je otestovat model na omezeném katalogu nástrojů a na vlastním datasetu příkazů před rozšiřováním integrace.

• Needle – repozitář projektu
• Needle – dokumentace fine-tuningu
• Needle 2 – modelová karta