Ghid Workspace Tools: unelte Python apelate de model în Open WebUI: configurare și exemple practice

Uneltele se scriu sau se importă în Workspace > Tools (ENABLE_TOOLS, activ implicit). Fișierul are un docstring de început cu metadate (title, description, requirements, version) și o clasă Tools. Orice metodă publică devine unealtă, deci metodele ajutătoare încep cu _. Textul docstringului de dinaintea primului :param devine descrierea uneltei, iar fiecare :param nume: descrierea argumentului; un bloc Args: în stil Google nu este citit. Fiecare argument are nevoie de un type hint, din care se generează schema JSON trimisă modelului.

Setările stau în clasa Valves (completată de administrator) și UserValves (de fiecare utilizator), iar __init__ trebuie să conțină self.valves = self.Valves(), altfel valorile salvate nu se încarcă. Cheile API puse în Valves rămân pe server: modelul vede doar rezultatul. Argumentele speciale, ca __user__, __event_emitter__, __metadata__, __files__ sau __oauth_token__, se adaugă în semnătura metodei când sunt necesare. Documentația recomandă metode async. O unealtă poate întoarce str, dict sau list.

În chat, uneltele se pornesc din meniul Integrations (lângă +) > Tools, sau se leagă permanent de un model în Workspace > Models. În modul Native (implicit din v0.10.0) modelul decide singur ce unealtă apelează, deci are nevoie de suport bun pentru function calling. Un Tool rulează cod arbitrar pe server: documentația echivalează dreptul de a crea sau importa unelte cu acces la shell. Pentru extensii ale platformei (modele noi, filtre, butoane) există Functions, iar pentru servicii externe, servere OpenAPI sau MCP.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`class Tools`	Clasa obligatorie; fiecare metodă publică este o unealtă.
`Docstringul fișierului`	Metadate: `title`, `description`, `requirements` (pachete pip instalate la încărcare), `version`, `required_open_webui_version`.
`:param nume:`	Descrierea unui argument; restul docstringului de dinainte descrie unealta.
`Type hints`	Obligatorii; un argument fără tip apare ca text în schemă.
`Valves / UserValves`	Setări de administrator, respectiv de utilizator (în `__user__["valves"]`).
`__event_emitter__`	Trimite stări și notificări în interfață în timpul rulării.
`__user__ / __metadata__ / __files__`	Utilizatorul, metadatele chatului și fișierele atașate.
`__oauth_token__`	Tokenul OAuth al utilizatorului, reîmprospătat automat.

Exemple practice și scenarii reale

Exemplul 1: O unealtă care numără zilele lucrătoare

Testată local cu pydantic, în afara Open WebUI. Docstringul metodei este ce citește modelul.

"""
title: Zile lucrătoare
description: Numără zilele de luni până vineri dintre două date
version: 0.1.0
"""
from datetime import date, timedelta
from pydantic import BaseModel, Field


class Tools:
    class Valves(BaseModel):
        max_zile: int = Field(3660, description="Intervalul maxim acceptat, în zile")

    def __init__(self):
        self.valves = self.Valves()

    async def zile_lucratoare(self, inceput: str, sfarsit: str) -> str:
        """
        Numără zilele de luni până vineri dintre două date, inclusiv capetele.
        :param inceput: Data de început, în formatul AAAA-LL-ZZ.
        :param sfarsit: Data de sfârșit, în formatul AAAA-LL-ZZ.
        """
        a, b = date.fromisoformat(inceput), date.fromisoformat(sfarsit)
        if b < a or (b - a).days > self.valves.max_zile:
            return "Interval invalid."
        zile = sum(1 for i in range((b - a).days + 1) if (a + timedelta(days=i)).weekday() < 5)
        return f"{zile} zile lucrătoare"

Exemplul 2: Stare afișată în timp ce unealta rulează

async def raport(self, luna: str, __event_emitter__=None) -> str:
    """
    Generează raportul lunar.
    :param luna: Luna, în formatul AAAA-LL.
    """
    await __event_emitter__({"type": "status", "data": {"description": "Se adună datele...", "done": False}})
    rezultat = f"Raport pentru {luna}"
    await __event_emitter__({"type": "status", "data": {"description": "Gata", "done": True}})
    return rezultat

Exemplul 3: Activarea uneltei

Într-un chat:   Integrations (lângă +) > Tools > Zile lucrătoare
Pe un model:    Workspace > Models > (modelul) > Tools > Zile lucrătoare > Save & Update

Greșeli frecvente și capcane

Descrii parametrii cu un bloc Args:: nu este citit, iar modelul primește parametri fără descriere.
Uiți self.valves = self.Valves() în __init__: unealta rulează mereu cu valorile implicite, orice ar salva administratorul.
Lași metode ajutătoare fără _ la început: apar modelului ca unelte separate.

`Workspace Tools: unelte Python apelate de model` în Open WebUI & RAG Local