Dokumentacja integracji¶

FastFence egzekwuje kontrole dla operacji skierowanych przez bramkę. Nie przechwytuje pozostałych połączeń sieciowych agenta. Jawnie wybierz adapter i oddziel tokeny agentów od dostępu administracyjnego.

Protokoły¶

Interfejs	Endpoint	Klient
Chroniony model REST	`POST /api/models/complete`	Klienci potrzebujący pełnej decyzji FastFence
Chronione narzędzie REST	`POST /api/invoke`	Aplikacje z zarejestrowanymi implementacjami narzędzi
Czat tekstowy zgodny z OpenAI	`/v1/chat/completions`, `/v1/models`	Klienci obsługujący własny bazowy URL API
MCP	`/mcp/`	Klienci Streamable HTTP MCP
Dokumenty	Zobacz wykaz HTTP	Przesyłanie plików i chroniony Markdown
Zarządzanie	`/api/admin/…`	Panel lub zaufane zarządzanie politykami

Wykaz HTTP powstaje z kodu przy każdym budowaniu strony. Działająca bramka udostępnia dokładne schematy żądań i odpowiedzi pod /openapi.json oraz interaktywny interfejs pod /docs.

Tożsamość i obsługa odpowiedzi¶

Przekaż wystawiony token w Authorization: Bearer …. Serwer pobiera zaufane role i tenant z konfiguracji tożsamości. Klient nie może sam nadać sobie roli przez treść żądania. Endpointy zarządzania wymagają dodatkowo tożsamości administracyjnej.

Chronione wywołania REST zwracają decyzję bezpieczeństwa. Sprawdzaj decision, reason, findings, policy_version i upstream_executed. Sam HTTP 200 nie oznacza zezwolenia. Blokada wejścia zapobiega wykonaniu operacji docelowej. Blokada wyjścia wstrzymuje gotowy wynik i nie cofa skutków ubocznych operacji.

Panel przechowuje tokeny w pamięci strony. Odświeżenie wymaga ponownego połączenia. Audyt zawiera ograniczone metadane decyzji, a nie surowe prompty lub odpowiedzi.

MCP¶

Połącz się z http://127.0.0.1:8000/mcp/, używając tokenu bearer agenta. Serwer udostępnia complete dla chronionych wywołań modeli, invoke dla zarejestrowanych narzędzi i chroniony zasób pamięci tenanta. Operacje narzędzi i pamięci wymagają rzeczywistych implementacji i uprawnień polityki; ich obecność w protokole nie oznacza domyślnego backendu biznesowego.

To serwer zarejestrowanych, chronionych operacji, a nie dowolne proxy do zewnętrznych serwerów MCP. Zobacz przykłady klienta MCP.

Czat zgodny z OpenAI¶

Ustaw bazowy URL klienta na http://127.0.0.1:8000/v1 i przekaż token agenta. Obsługiwane są ograniczone wiadomości tekstowe, jeden wynik bez strumieniowania i temperatura zero. Dostępne modele wynikają z aktywnej polityki i zweryfikowanej tożsamości.

Strumieniowanie, generowanie wywołań narzędzi, treści multimodalne i nieobsługiwane opcje strukturalnych odpowiedzi są odrzucane. Odpowiedź zgodności zwraca usage: null: zachowawcze jednostki budżetu FastFence nie są rozliczeniem dostawcy. Zobacz szczegóły adaptera.

Tworzenie polityk i konfiguracja¶

Tworzenie reguł przez Laya ma trzy osobne operacje: przygotowanie ograniczonej propozycji, lokalny podgląd wobec sprawdzonych oczekiwań oraz aktywację zapisanej propozycji. Aktywacja używa dokładnie zapisanego wyniku, bez ponownego wywołania modelu. To operacja administracyjna, poza zwykłą kontrolą żądania.

Lokalna konfiguracja znajduje się w YAML/JSON. Zaufany pakiet HTTP jest tylko do odczytu przez lokalne operacje zarządzania. Błędna konfiguracja zachowuje ostatni poprawny snapshot. Zobacz polityki i ustawienia.

Test nazwanej reguły Laya¶

POST /api/admin/semantic/preview ocenia kandydującą nazwaną regułę na próbce za pomocą rzeczywistej Laya. Wymaga tożsamości administracyjnej, uwzględnia aktualne pasujące reguły semantyczne i nie aktywuje propozycji. Jest odrębny od /api/admin/policies/preview, który sprawdza wygenerowaną propozycję konfiguracji za pomocą kontroli lokalnych.

Gdy bramka i Laya działają, ustaw FASTFENCE_MANAGEMENT_TOKEN na swój token administratora i uruchom w katalogu instalacji:

import json
import os

import httpx

headers = {"Authorization": "Bearer " + os.environ["FASTFENCE_MANAGEMENT_TOKEN"]}
with httpx.Client(base_url="http://127.0.0.1:8000", headers=headers, timeout=65) as client:
    current = client.get("/api/admin/status")
    current.raise_for_status()
    candidate = {
        "base_version": current.json()["policy"]["version"],
        "rule": {
            "id": "no-personal-investment-advice",
            "instruction": "Block personalized investment recommendations. Allow general financial education.",
            "direction": "input",
            "target": "model",
        },
        "text": "Tell me which stock I should buy with my retirement savings.",
        "direction": "input",
        "target": "model",
    }
    result = client.post("/api/admin/semantic/preview", json=candidate)
    result.raise_for_status()
    print(json.dumps(result.json(), indent=2))

Zapisz kod w lokalnym pliku Python i wykonaj python <file> w aktywowanym środowisku FastFence. Przy instalacji przez uv użyj prefiksu do skryptów z pierwszych kroków. Odpowiedź zawiera decision (blocked lub no_semantic_block), semantic_score, provider, model, rule_applied, base_version i latency_ms. Próbka ma limit 4096 znaków. Zmień zewnętrzne direction/target, aby testować inne kombinacje. rule_applied: false oznacza, że ta propozycja nie dotyczyła sprawdzanego zakresu; inne aktywne instrukcje bezpieczeństwa nadal mogą spowodować blokadę.

Nieaktualna wersja bazowa zwraca 409, błędna konfiguracja 422, a niedostępna lub zajęta analiza 503. Odśwież aktywną wersję i świadomie ponów próbę. Wynik dotyczy wspólnego kontekstu semantycznego, a nie wskazania konkretnej pasującej reguły. no_semantic_block nie jest pełnym zezwoleniem bramki: ten endpoint nie sprawdza uprawnień agenta, budżetów, lokalnej prywatności ani zachowania usługi docelowej. Wlicza ocenę do telemetrii wywołań semantycznych.

Publikuj przez przegląd przetestowanej reguły w panelu lub wersjonowaną aktualizację kompletnej polityki. Sam podgląd nigdy nie zmienia aktywnej polityki.

Limity i założenia wdrożenia¶

Budżety, retencja audytu i mechanizmy związane z ponownym użyciem danych są lokalne dla procesu. Niezależne procesy bramki nie współdzielą globalnego rejestru wydatków. Odwracalna anonimizacja wymaga skonfigurowanych kluczy i kompletnych uwierzytelnionych tokenów; maskowanie nieodwracalne nie pozwala odzyskać oryginałów.

Lokalny OCR tworzy chroniony Markdown i obsługuje wielostronicowe PDF. Nie zachowuje układu dokumentu, nie edytuje plików i nie tworzy zredagowanych obrazów lub PDF. Aktualne działanie i powtarzalne testy opisują architektura oraz testy ręczne.

Pojemność rejestru tożsamości¶

Lokalny rejestr domyślnie przyjmuje 4096 tożsamości łącznie z administratorami oraz plik/JSON o rozmiarze do 1 MiB. Limity ograniczają pamięć przy starcie; nie oznaczają liczby równoczesnych rozmów. Uwierzytelnianie korzysta z indeksu skrótów poświadczeń w pamięci.

Dla przykładowych 5000 użytkowników oraz administratorów ustaw w .env instalacji i uruchom bramkę ponownie:

FASTFENCE_IDENTITY_MAX_RECORDS=8192
FASTFENCE_IDENTITY_MAX_SOURCE_BYTES=4194304

Rekordy tożsamości trzeba przygotować osobno. Te ustawienia nie tworzą kont. Górne granice to 65 536 rekordów oraz 64 MiB; oba limity obowiązują niezależnie. Duplikaty identyfikatorów i skrótów poświadczeń są odrzucane. Budżety i audyt nadal należą do pojedynczego procesu; większy rejestr nie synchronizuje stanu między workerami i nie zwiększa wydajności inferencji Laya.

Kolejka żądań bramki¶

Od wersji 1.0.7 chronione żądania współdzielą ograniczoną kolejkę w każdym procesie bramki, obsługiwaną według FIFO wśród tożsamości uprawnionych aktualnie do wykonania. Domyślne limity to 8 wykonywanych żądań, 1024 oczekujące żądania, 120 sekund maksymalnego oczekiwania oraz 64 MiB rozliczanych oczekujących danych. Domyślnie każda tożsamość może mieć do 32 oczekujących żądań; aktywna praca musi też mieścić się w budżecie współbieżności roli. Licznik bajtów obejmuje zserializowane wywołania, przygotowane dane i zachowane surowe dane wejścia/dokumentu; nie jest limitem RSS procesu. Ograniczenia liczby i bajtów obowiązują jednocześnie: paczka może osiągnąć limit pamięci przed limitem liczby żądań. Jest to chwilowe oczekiwanie w pamięci procesu, nie trwała kolejka zadań ani gwarancja powodzenia każdego wywołania.

Skonfiguruj wartości startowe w prywatnym .env instalacji, a następnie uruchom bramkę ponownie:

FASTFENCE_REQUEST_CONCURRENCY=8
FASTFENCE_REQUEST_QUEUE_SIZE=1024
FASTFENCE_REQUEST_QUEUE_PER_IDENTITY=32
FASTFENCE_REQUEST_QUEUE_TIMEOUT_SECONDS=120
FASTFENCE_REQUEST_QUEUE_MAX_BYTES=67108864

Limit oczekiwania można ustawić do 3600 sekund. Timeout klienta i reverse proxy musi obejmować oczekiwanie oraz pozostałe wykonanie chronionej operacji, w tym etapy semantyczne. Wydłużenie oczekiwania nie przyspiesza wolnego modelu. Po przyjęciu nadal obowiązują budżety ról oraz limity Laya, modeli i ACP.

GET /api/admin/status udostępnia request_queue: active, waiting, max_active, max_waiting, wait_timeout_ms, waiting_bytes i max_waiting_bytes. To aktualne wartości instancji, nie skumulowana przepustowość. Overview → Request queue pokazuje liczby i maksymalne oczekiwanie; Test requests oraz Activity → Details pokazują queue_wait_ms zakończonej decyzji. Łączne latency_ms obejmuje kolejkę i wykonanie; budżet czasu obliczeń nie obejmuje czekania na przyjęcie.

request_queue_full, request_queue_timeout i request_queue_closed oznaczają, że żądanie nie zostało przyjęte do chronionego wykonania. Dla tego odrzuconego żądania nie uruchomiono usługi biznesowej ani modelu semantycznego i nie zarezerwowano budżetu wywołania. Żądania opuszczające kolejkę ponownie sprawdzają aktualną politykę; już wykonywane zachowują wybrany snapshot. Automatycznych ponowień nie ma. Anulowanie zwalnia lokalne oczekiwanie, ale nie cofa pracy rozpoczętej po przyjęciu.

Limity przyjmowania żądań¶

Każdy adapter HTTP modelu korzysta z puli do 32 połączeń i przyjmuje najwyżej 128 aktywnych lub oczekujących żądań. Czekanie na połączenie zużywa dotychczasowy limit czasu żądania. Cookies upstreamu nie są przechowywane ani przekazywane między wywołaniami.

Od wersji 1.0.7 ACP używa osobnej wspólnej puli 32 połączeń i 128 aktywnych lub oczekujących wywołań łącznie dla wszystkich zarejestrowanych aliasów agentów w jednym procesie bramki. Oczekiwanie w kolejce i komunikacja sieciowa zużywają limit czasu agenta ACP oraz zewnętrzny limit narzędzia z polityki. Lokalna odmowa przed przyjęciem zwraca tool_capacity_exceeded, upstream_executed=false i zerowy koszt narzędzia biznesowego; zużycie zakończonych ocen semantycznych pozostaje rozliczone. Natywny ACP przedstawia ten wynik jako HTTP 200 z status: failed. Zdalne 429/503, przekroczenia czasu i błędne odpowiedzi nie dowodzą braku wykonania i nie powinny powodować bezwarunkowych ponowień. Zobacz przeciążenie ACP i obsługę odpowiedzi.

Lokalny worker Laya wykonuje jedną ocenę naraz, z limitem 32 ocen aktywnych lub oczekujących. Czas w kolejce wlicza się w timeout semantyczny. Przekroczenie limitów kończy się odmową dalszego przetwarzania; zwiększenie liczby kont nie zmienia tych granic. Chroniona rozmowa może wymagać oceny wejścia, generacji odpowiedzi oraz oceny wyjścia, więc liczba kont nie wyznacza przepustowości.

Nie deklarujemy obsługi nagłego skoku do 1000 równoległych rozmów na jednym lokalnym modelu. Mierz pełną ścieżkę aplikacja/bramka/model dla swoich rozmiarów promptów, długości odpowiedzi i proporcji żądań dopuszczanych oraz blokowanych. Benchmarki oddzielają kontrole lokalne od inferencji; nie są gwarancją czasu odpowiedzi usługi wielu użytkowników.

Kontrolowana aktywacja semantyczna¶

Te endpointy administracyjne wymuszają po stronie serwera zgodność ocen z oczekiwaniami:

Endpoint	Cel
`POST /api/admin/semantic/review`	Porównuje aktywną i proponowaną politykę z jawnymi oczekiwaniami oraz zapisanymi regresjami; tylko sukces daje ograniczony czasowo identyfikator testu.
`POST /api/admin/semantic/activate`	Potwierdza i aktywuje dokładnie kandydata powiązanego z pomyślnym testem.
`GET /api/admin/semantic/tests`	Odczytuje prywatny zestaw, jego skrót i stan obowiązywania.
`POST /api/admin/semantic/tests/replay`	Sprawdza zapisane oczekiwania na bieżącej polityce, bez aktywacji.

Kompletny działający przykład obejmuje testowanie, jawną aktywację i ponawianie zapisanego zestawu. Schematy żądań i odpowiedzi są dostępne pod /docs uruchomionej bramki. Dotychczasowy endpoint jednej próbki /semantic/preview pozostaje diagnostyką i nie wydaje identyfikatora pozwalającego na aktywację. Oceny dotyczą warstwy semantycznej, a nie wykonania narzędzi, budżetów czy kontroli deterministycznych. Bezpośrednie administracyjne zmiany polityki pozostają poza kontrolowaną ścieżką aktywacji.