Pluginy

​

Przegląd

​

Fazy

​

Wykonywanie łańcucha

• Kroki wykonują się w kolejności rosnącej. Późniejszy krok widzi edycje wcześniejszego.
• W obrębie kroku instancje, których manifest mówi Mutates: false, działają współbieżnie na płytkiej kopii wymiany (ich Values i nagłówki odpowiedzi są scalane z powrotem). Krok może zawierać co najwyżej jedną instancję z Mutates: true, która działa po instancjach czytających. Dwie modyfikujące instancje w tym samym kroku to błąd konfiguracji.
• Decyzje kroku są scalane według wagi: block > respond > warn > allow. Pierwsza decyzja blokująca kończy łańcuch po swoim kroku.

​

Decyzje

​

Ścieżka audytu

​

Tryby błędów i timeouty

​

Cykl życia instancji

​

Streaming

​

Exchange

​

Konfiguracja

​

Włączanie systemu pluginów

plugins:
  enabled: true    # PLUGINS_ENABLED; domyślnie: false

​

Instancje

guardrails:
  enabled: true
  rules:
    - name: "mask-keys"
      type: "string_replace"      # wbudowany typ albo nazwa z manifestu załadowanego pluginu
      phase: "response"           # prompt (domyślnie) | response | stream
      order: 10                   # krok w obrębie fazy
      fail_mode: "open"           # closed (domyślnie) | open
      timeout_ms: 500             # 0 = brak timeoutu dla instancji (domyślnie)
      config:                     # walidowane względem ConfigSchema pluginu
        mode: "regex"
        rules: |
          sk-[A-Za-z0-9]{20,} => [redacted]

​

Ładowanie plików .so

plugins:
  search_paths: ["/etc/gomodel/plugins"]   # PLUGINS_SEARCH_PATHS, rozdzielone przecinkami; domyślnie: puste
  load:
    - file: acme_guard.so                  # względem ścieżki wyszukiwania albo bezwzględna
      sha256: "3b1f..."                    # opcjonalne przypięcie; niezgodność przerywa start

​

Dashboard

• Strona Plugins & Guardrails: Create Guardrail wyświetla każdy plugin, który implementuje hook prompt, response lub stream. Formularz jest generowany z ConfigSchema pluginu: text, textarea, number, select, checkboxes, bool (przełącznik), list (wpisy tekstowe, po jednym w linii, zapisywane jako tablica stringów), secret (maskowane; GET zwraca ********, a odesłanie tej dosłownej wartości zachowuje zapisaną wartość) oraz model (ten sam wyszukiwalny selektor modeli co w playgroundzie i edytorach modeli wirtualnych, wyświetlający modele gatewaya; alias lub model wirtualny wpisuje się ręcznie). Sekcja Advanced zawiera Fail mode (Default, Closed, Open) i Timeout (ms); dotyczą one instancji w każdym workflow, który się do niej odwołuje.
• Lista pluginów: na dole strony Plugins & Guardrails każdy załadowany typ pluginu z tytułem i nazwą (Header Edit, a potem header_edit – nazwa jest tym, do czego odwołuje się konfiguracja), wersją, hookami, źródłem (built-in, registered lub ścieżka .so) i stanem zdrowia. Pluginy guardrails (te, których instancje stosują politykę do promptów, odpowiedzi lub streamów) mają ikonę tarczy i są wyświetlane jako pierwsze; strategie routingu też są pluginami, ale nie guardrails. Plugin, którego nie udało się załadować, jest wyświetlany z błędem. Strona jest widoczna zawsze, gdy system pluginów jest włączony.
• Strona Workflows: każdy krok ma selektor Phase; lista rozwijana instancji oferuje tylko instancje, których plugin implementuje tę fazę.

​

Pluginy shared object

• Platforma: Linux, macOS i FreeBSD, i tylko w pliku binarnym zbudowanym z CGO_ENABLED=1. Domyślny plik binarny i obraz GoModel są statyczne i odrzucają pliki .so z błędem, który to wyjaśnia. Użyj make build-plugins (bin/gomodel-plugins) albo obrazu gomodel:<version>-plugins (make image-plugins, budowany z Dockerfile.plugins, runtime glibc).
• Dokładnie ten sam toolchain: plugin musi być zbudowany tą samą wersją Go, z tymi samymi flagami builda (-trimpath, -race, -tags) i z identycznymi źródłami każdego współdzielonego pakietu. Współdzielone są tylko biblioteka standardowa i pluginapi, więc wewnętrzne zmiany w GoModel nigdy nie wpływają na plugin, ale każdy release GoModel i każda aktualizacja toolchaina Go (łącznie z wydaniami poprawkowymi) wymaga przebudowania. Zrób z tego krok w CI.
• Brak wyładowywania: plik .so pozostaje załadowany do restartu. Zmiana załadowanego pliku zaczyna działać po restarcie; edycja konfiguracji instancji ponownie uruchamia Init na nowej wartości bez restartu.
• Zaufany kod: załadowanie .so jest równoważne zmianie pliku binarnego. Utrzymuj search_paths jako należące do roota i przypinaj sha256 na produkcji.

​

Budowanie i inspekcja

gomodel plugin build ./docs/example_plugins/keywordblock -o plugins/keyword_block.so
gomodel plugin inspect plugins/keyword_block.so
shasum -a 256 plugins/keyword_block.so     # wartość dla plugins.load[].sha256

plugin file /app/plugins/x.so was built with a different toolchain, flags, or
pluginapi sources: it was built with go1.27.3, gomodel v0.1.90, flags -trimpath;
this binary was built with go1.27.3, gomodel v0.1.91, flags (none). Rebuild it
with `gomodel plugin build` from this GoModel version

docker build -f Dockerfile.plugins --target plugin-builder -t gomodel-plugin-builder .
docker run --rm -v "$PWD/my-plugin:/src" -v "$PWD/plugins:/out" \
  gomodel-plugin-builder -o /out/my-plugin.so /src

​

Pisanie pluginu

package main

import (
	"context"
	"encoding/json"
	"strings"

	"github.com/enterpilot/gomodel/pluginapi"
)

type wordBlock struct {
	words   []string
	enforce pluginapi.Enforcement
}

func (p *wordBlock) Manifest() pluginapi.Manifest {
	return pluginapi.Manifest{
		Name:      "word_block",
		Version:   "1.0.0",
		Kinds:     []pluginapi.Kind{pluginapi.KindPrompt},
		Guardrail: true,
		ConfigSchema: []pluginapi.Field{
			{
				Key: "words", Label: "Blocked words", Input: pluginapi.InputList,
				Required: true, Help: "One word per line.",
			},
			{
				Key: "action", Label: "On match", Input: pluginapi.InputSelect, Default: "block",
				Help: "Block rejects, respond answers with the message, warn records the match.",
				Options: []pluginapi.Option{{Value: "block", Label: "Block"}, {Value: "respond", Label: "Respond"}, {Value: "warn", Label: "Warn"}},
			},
			{Key: "message", Label: "Message", Input: pluginapi.InputText, Default: "request blocked by policy", Help: "Error, reply, or audit note."},
			pluginapi.BlockStatusField(),
		},
	}
}

func (p *wordBlock) Init(_ context.Context, raw json.RawMessage, _ pluginapi.Host) error {
	cfg, err := pluginapi.ParseConfig("word_block", p.Manifest().ConfigSchema, raw)
	if err != nil {
		return err
	}
	for _, w := range cfg.List("words") {
		p.words = append(p.words, strings.ToLower(w))
	}
	p.enforce = pluginapi.Enforcement{
		Action:      pluginapi.Action(cfg.Choice("action", "block", "block", "respond", "warn")),
		Message:     cfg.String("message", "request blocked by policy"),
		BlockStatus: cfg.BlockStatus("block_status"),
	}
	return cfg.Err()
}

func (p *wordBlock) Close(context.Context) error { return nil }

func (p *wordBlock) OnPrompt(_ context.Context, x *pluginapi.Exchange) (pluginapi.Decision, error) {
	if x.Prompt == nil || x.Prompt.LastUser() == nil {
		return pluginapi.Allow(), nil
	}
	text := strings.ToLower(x.Prompt.LastUser().Text())
	for _, w := range p.words {
		if strings.Contains(text, w) {
			return p.enforce.Enforce("word_block", map[string]any{"word": w}), nil
		}
	}
	return pluginapi.Allow(), nil
}

func GoModelPlugin() pluginapi.Plugin { return &wordBlock{} }

func main() {}

• Init otrzymuje konfigurację po walidacji względem ConfigSchema: z zastosowanymi wartościami domyślnymi, skonwertowanymi liczbami, wartościami logicznymi i listami, odrzuconymi nieznanymi kluczami i sprawdzonymi kluczami wymaganymi. Liniowe pola textarea przyjmują listę stringów YAML oraz block scalar; pola list przyjmują listę lub jedną linię rozdzieloną przecinkami i docierają jako tablica JSON; pola bool przyjmują true/false jako wartości logiczne lub tekst i docierają jako wartość logiczna JSON. Metoda jest wywoływana raz dla każdej skonfigurowanej instancji i ponownie, gdy instancja jest edytowana.
• Czytaj konfigurację przez pluginapi.ParseConfig i jego typowane metody odczytu (String, Choice, Bool, Int, Float, OptionalFloat, List, Lines, Roles, BlockStatus) zamiast struktury: każda metoda stosuje te same konwersje, których potrzebują dashboard i config.yaml, zwraca swoją wartość domyślną w razie problemu, a Err() raportuje pierwszy z nich ze wskazaniem klucza, więc dekoder to prosta lista przypisań i jedno sprawdzenie. RoleOptions() to lista checkboxów rozumiana przez Roles.
• Zwracaj wyniki przez pluginapi.Enforcement: wczytaj do niego action, message, block_status i opcjonalnie respond_text, a następnie Enforce(code, detail) zwróci błąd blokady, completion odpowiedzi lub ostrzeżenie, a Reject(code, detail) zwróci blokadę lub odpowiedź nawet wtedy, gdy akcja to warn (dla wyniku, który nie może przejść). BlockStatusField() to standardowe pole block_status. Wbudowane guardrails współdzielą ten mechanizm, więc ich block, respond i warn zachowują się tak samo.
• Eksportuj konstruktor (func GoModelPlugin() pluginapi.Plugin), aby jeden plik mógł obsługiwać kilka instancji. var GoModelPlugin pluginapi.Plugin też działa, ale ogranicza plik do jednej instancji.
• Ustaw Mutates: true, gdy plugin edytuje Prompt, Response lub stream. Niemodyfikujące pluginy mogą współdzielić krok i działać współbieżnie.
• Ustaw Guardrail: true, gdy instancje pluginu są guardrails: politykami stosowanymi do promptów, odpowiedzi lub streamów, niezależnie od tego, czy blokują, odpowiadają, ostrzegają czy przepisują. Każdy wbudowany plugin działający na ruchu to ustawia (llm_judge, string_replace, tag_replace, header_edit, system_prompt, llm_based_altering); strategia routingu, taka jak cheapest_healthy, nigdy nie dotyka ruchu i zostawia ją na false. Runtime ignoruje tę flagę; dashboard oznacza pluginy guardrails i ich instancje ikoną tarczy i wyświetla je jako pierwsze.
• Host przekazany do Init oferuje Logger() (wstępnie oznaczony pluginem i instancją), Inference().Complete(...) (chat completion przez gateway z originem plugin, w scope <user path>/guardrails/<instance> na potrzeby budżetów i audytu), Metrics() (nazwy z prefiksem plugin_<name>_) oraz HTTPClient() do wywołań usług zewnętrznych, takich jak klasyfikator lub detektor PII. Klient jest współdzielony przez wszystkie instancje, korzysta ze zmiennych środowiskowych proxy i puli połączeń gatewaya i ma timeout 60 s jako zabezpieczenie; buduj requesty przez http.NewRequestWithContext, aby timeout_ms instancji ograniczał każde wywołanie. History() zwraca błąd w tym release.
• Host implementuje też opcjonalny pluginapi.DecisionsHost. Sprawdź go asercją typu na Host, a następnie wywołaj Decisions().Decide(ctx, req), aby zadać modelowi decyzyjnemu typowane pytania o wejście, tak jak robi to POST /v1/decisions. Pytanie to predicate (prawdopodobieństwo odpowiedzi „tak”), choice lub score. Wywołanie ma ten sam scope i rozliczanie co Inference().Complete. Decisions().DecisionModel(model) informuje, czy model odpowiada tylko na decyzje, jak każdy model jev. llm_judge używa obu metod, żeby blokować na podstawie prawdopodobieństwa zamiast parsować werdykt czatu:
  if dh, ok := host.(pluginapi.DecisionsHost); ok {
  	result, err := dh.Decisions().Decide(ctx, pluginapi.DecisionRequest{
  		Model:     "jev/jev-latest",
  		Input:     []pluginapi.Message{pluginapi.TextMessage(pluginapi.RoleUser, text)},
  		Questions: []pluginapi.Question{{Type: pluginapi.QuestionPredicate, Name: "spam", Instructions: "Is this spam?"}},
  	})
  	// result.Answers[0].Probability, chyba że result.Answers[0].Refused()
  }
  
• Dodaj Summarize(config json.RawMessage) string, aby wyświetlać jednolinijkowe podsumowanie na liście guardrails, oraz Normalize(config) (json.RawMessage, error), aby kanonizować konfigurację przed zapisaniem. Obie metody są opcjonalne.
• Zaimplementuj pluginapi.HealthChecker (Health(ctx) error), gdy instancja zależy od czegoś poza procesem, na przykład od sidecara z klasyfikatorem. GoModel sprawdza ją poza ścieżką requestu po zbudowaniu instancji i przy każdym odświeżeniu guardrails (workflows.refresh_interval, domyślnie jedna minuta), z terminem 5 s. Nieudane sprawdzenie oznacza instancję jako degraded w GET /admin/guardrails i w dashboardzie, z błędem jako przyczyną, i jest logowane raz przy każdej zmianie stanu; treść błędu nie może zawierać sekretów i jest obcinana do 256 znaków. Stan zdrowia ma charakter informacyjny: ruch nadal przechodzi przez instancję zgodnie z jej fail_mode.
• Zaimplementuj pluginapi.ContentEditor (EditsContent() bool), gdy plugin, który deklaruje Mutates, można skonfigurować tak, by nie edytował, na przykład detektor ustawiony na oznaczanie zamiast przepisywania. GoModel pyta skonfigurowaną instancję przed pracą wykonywaną tylko dla pluginów edytujących – odtworzeniem zapisanej historii łańcuchowego requestu Responses zamiast pozwolić providerowi samodzielnie rozwiązać previous_response_id. Nigdy nie zmienia to sposobu działania hooka, a modyfikujący plugin bez tego interfejsu jest traktowany jako edytujący.
• Pola wejściowe secret i model istnieją dla kluczy API zewnętrznych klasyfikatorów i dla selektorów modeli; wartość secret jest maskowana w każdej odpowiedzi administracyjnej. Używaj bool dla przełącznika i list dla otwartej listy stringów (typy encji, lista dozwolonych) zamiast kodować je w select lub textarea.
• Dodaj Scope: pluginapi.ScopeRoute do pól, które należą do modelu wirtualnego, a nie do instancji (tylko strategie routingu).

​

Testowanie pluginu

• plugintest.NewHost(replies...) to sztuczny Host: zaplanowane odpowiedzi inferencji (albo funkcja Reply, albo Err), decyzje rozstrzygane przez funkcję Answer (bez niej każde pytanie dostaje odmowę), DecisionModels dla DecisionModel, zapisane Requests() i DecisionRequests(), zapisane metryki Recorded() i ustawialny klient HTTP dla sztucznego sidecara uruchomionego przez httptest.
• plugintest.Init, Text, Prompt, Completion i Exchange budują fixtures potrzebne do wywołania hooka, z czystym śledzeniem zmian i zbiorem Values.
• plugintest.RunStream(ctx, hook, x, events) steruje StreamHook tak, jak robi to host zgodnie z jego StreamPolicy: łączenie chunków, wstrzymany ogon lookbehind pokazywany ponownie z Overlap, pass, replace, drop i terminate stosowane do całego okna oraz tryb buforowany składający completion dla OnResponse. Wynik zawiera tekst, który klient otrzymałby dla każdego choice, dostarczone zdarzenia, decyzję terminate i decyzję końcową.

p := plugintest.Init(t, New, `{"rules": "secret => [x]", "stream_lookbehind": 4}`, nil)
res, err := plugintest.RunStream(ctx, p.(pluginapi.StreamHook), plugintest.Exchange(nil, nil), []*pluginapi.StreamEvent{
	plugintest.TextDelta("my se"), plugintest.TextDelta("cret is safe"),
})
// res.Text[0] == "my [x] is safe": dopasowanie podzielone między dwie delty zostało przepisane raz.

​

Pluginy strategii routingu

type RouteStrategy interface {
	Select(ctx context.Context, req RouteRequest) (RouteChoice, error)
	OnAttemptEnd(outcome RouteOutcome)
}

virtual_models:
  - source: smart-router
    strategy: plugin                    # round_robin | cost | failover | adaptive | plugin
    strategy_plugin: cheapest_healthy   # nazwa pluginu; wymagana przy strategy: plugin
    strategy_config:                    # pola pluginu ze Scope: route; po pominięciu obowiązują wartości domyślne
      prefer: cheapest                  # cheapest | fastest
      max_error_rate: 0.2
    targets:
      - openai/gpt-4o-mini
      - anthropic/claude-haiku-4-5

• strategy_config jest walidowane względem pól pluginu w scope route (route_fields w GET /admin/plugins). strategy: plugin bez strategy_plugin to błąd walidacji, a PUT /admin/virtual-models odrzuca nazwę, która nie jest załadowanym pluginem z hookiem route.
• weight celu jest ignorowane przy strategii plugin.
• Pola pluginu route w scope instancji (endpoint, klucz API) pochodzą z definicji guardrails, której nazwa i typ są równe nazwie pluginu; bez niej plugin jest inicjalizowany z {}. Wartości secret w scope instancji docierają obecnie do pluginu route zamaskowane. Zapisanie tej definicji przebudowuje instancję; poprzednia jest zamykana, gdy jej trwające wywołania Select się zakończą.
• GoModel wraca do ważonego round robin, logując jedno ostrzeżenie na model wirtualny, gdy pluginu brakuje, nie jest pluginem route, nie udało się go zainicjalizować, strategy_config jest nieprawidłowe albo Select zwraca błąd, panikuje, trwa dłużej niż 250 ms lub zwraca cel spoza puli dostępnych celów.

​

Endpointy administracyjne

​

GET /admin/plugins

[
  {
    "name": "string_replace",
    "label": "String Replace",
    "version": "1.0.0",
    "description": "Replaces, flags, or blocks text matching literal or regex rules in prompts, responses, and streams.",
    "kinds": ["prompt", "response", "stream"],
    "mutates": true,
    "guardrail": true,
    "source": "builtin",
    "fields": [{ "key": "rules", "label": "Rules", "input": "textarea", "required": true }],
    "route_fields": [],
    "health": "ok",
    "error": ""
  }
]

​

GET /admin/guardrails/types

{
  "type": "llm_judge",
  "label": "LLM Judge",
  "description": "Asks a judge model whether prompts and responses violate a policy, then blocks, answers, or flags them.",
  "defaults": { "action": "block", "max_tokens": 256, "target": "auto" },
  "fields": [{ "key": "model", "label": "Judge model", "input": "model", "required": true }],
  "phases": ["prompt", "response", "stream"],
  "source": "builtin",
  "mutates": false,
  "guardrail": true
}

​

GET, PUT, DELETE /admin/guardrails

​

GET /admin/workflows/guardrails

[{ "name": "pii-redact", "type": "llm_based_altering", "phases": ["prompt", "response"], "summary": "openai/gpt-4o-mini • user • default prompt" }]

​

Payload workflow w wersji 2