====== Needle ======

//Vytvořeno: **18.8.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/cactus-compute/needle|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.

===== Princip fungování =====

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:

<code json>
{
  "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"]
  }
}
</code>

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

<code json>
{
  "name": "set_light",
  "arguments": {
    "entity_id": "light.pracovna",
    "state": "on"
  }
}
</code>

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.

===== Možné použití se Smart Home =====

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

  - STT převede řeč na text; podle zvoleného řešení může předcházet překlad do angličtiny.
  - Needle z textu a omezeného katalogu schémat vybere strukturované volání.
  - Validovaná integrační vrstva zkontroluje oprávnění, parametry a kontext.
  - 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.

===== Návrh rozhraní pro model =====

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 a LoRA =====

[[https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md|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ů.

===== Jazyk, limity a ověření =====

[[https://huggingface.co/Cactus-Compute/needle2|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. [[https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md|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.

===== Zdroje =====

  * [[https://github.com/cactus-compute/needle|Needle – repozitář projektu]]
  * [[https://github.com/cactus-compute/needle/blob/main/doc/finetuning.md|Needle – dokumentace fine-tuningu]]
  * [[https://huggingface.co/Cactus-Compute/needle2|Needle 2 – modelová karta]]