🇬🇧 English version
Voir aussi : Fournisseurs de modèles · Fournisseurs LLM · ADR-015 · Retour à l'index
Modèles de décision
Un modèle de décision répond à des questions typées sur un état, avec des probabilités calibrées,
et n'écrit aucun texte. Orkeon l'atteint par le port IDecisionModel (Orkeon.Application) ; le
adaptateur sert trois fournisseurs de décision sur le protocole « System One » : TypeSafe (Jev), Liquid (d1) et Kev. Le
modèle juge et le code d'Orkeon agit : il bloque, route ou escalade un appel, classe des
passages, ou remet une décision à un agent
(ADR-015).
Le port
IDecisionModel.DecideAsync(DecisionRequest, ct) envoie une requĂŞte et renvoie une
DecisionResponse.
Une DecisionRequest porte :
state: le JSON sur lequel portent les questions (un texte, un objet, un document) ;questions: un dictionnaire d'un nom de votre choix vers une question ;assets(facultatif, des images nommées),model(facultatif, sinon le défaut configuré) etLongContext(non sérialisé : il pose l'en-tête de contexte long).
| Question | Ce que vous donnez | Ce que vous recevez |
|---|---|---|
choice |
une à 255 options nommées, chacune avec sa description | l'option choisie et la probabilité de chacune |
score |
un à dix niveaux d'une échelle ordonnée | le niveau et la probabilité de chacun |
noul |
l'énoncé ; criteria.true et criteria.false sont facultatifs |
noul, la probabilité de vrai |
box |
des images dans assets |
une zone dans une image |
Une réponse choice, score ou box porte aussi une confidence. Un DecisionRequestValidator refuse un jeu de questions
vide, un choice de plus de 255 options, un score de plus de dix niveaux, et une box sans images.
Fournisseurs de décision
Trois fournisseurs servent le même protocole « System One » : TypeSafe (modèle Jev), Liquid
(modèle d1) et Kev. Un seul client, SystemOneDecisionModel, les sert par trois descripteurs ;
la requête est POST <BaseUrl>/systemone avec model, state et questions, la réponse porte
answers et usage.
| Fournisseur | Adresse par défaut | Modèle par défaut | Variable de clé | Section |
|---|---|---|---|---|
typesafe |
https://api.typesafe.ai/v1 |
jev-latest |
TYPESAFE_API_KEY, obligatoire |
Orkeon:TypeSafe |
liquid |
https://api.liquid.ai/decisions/v1 |
d1.1 (ou d1-ultra) |
LIQUID_API_KEY, obligatoire |
Orkeon:Liquid |
kev |
http://127.0.0.1:8009/v1 |
kev-latest |
KEV_API_KEY, facultative : envoyée si donnée, sinon l'appel est sans authentification |
Orkeon:Kev |
services.AddOrkeonDecisionProvider(configuration);
Les trois binaires livrés (orkeon run, orkeon-host et orkeon-repl) l'appellent eux-mêmes, et
AddOrkeonDecisionProfiles dans tous les cas ; un hôte écrit en C# appelle les deux.
{
"Orkeon": {
"Decision": { "Provider": "typesafe" },
"TypeSafe": {
"Model": "jev-latest",
"TimeoutSeconds": 30,
"MaxRetries": 3
}
}
}
Le fournisseur actif
L'hôte démarre avec un fournisseur actif, ou aucun.
- Nommé :
Orkeon:Decision:Providervauttypesafe,liquidoukev(sans tenir compte de la casse ; une valeur vide compte comme non nommé). Toute autre valeur refuse le démarrage, en listant les noms valides. - Déduit, quand il n'est pas nommé : l'unique fournisseur hébergé (TypeSafe ou Liquid) qui a
une section de réglages (une clé présente sous
Orkeon, même vide, compte). Quand aucun n'a de section, celui dont la variable de clé est définie. Une section l'emporte sur une clé seule : ce fournisseur-là est alors ignoré. - Refusé : les deux sections présentes, ou aucune section et les deux clés définies ; le message
nomme les deux fournisseurs et
Orkeon:Decision:Provider. - Aucun : rien de présent, aucun modèle de décision n'est enregistré.
- Kev n'est jamais déduit, seulement nommé. Une section
Orkeon:KevsansOrkeon:Decision:Providerest signalée dans le log de démarrage (quand aucun fournisseur n'est nommé, l'avertissement nommeOrkeon:Decision:Provider) (une ligne de log, pas un avis de réglages).
Le log de démarrage nomme le fournisseur actif, le modèle, l'adresse et named ou deduced.
Chaque section de fournisseur présente qui n'est pas l'active est nommée dans un avertissement (une
clé seule dans l'environnement n'est pas signalée). --no-decision (une exécution sans décisions)
vaut pour tous les fournisseurs.
Clés, adresses et erreurs
- La clé se donne de trois façons : la variable par défaut, une variable nommée dans
ApiKeyEnvVar, ouApiKeydans la section du fournisseur. Elle n'apparaît jamais dans un log, une erreur ou un appel de tool. Un fournisseur hébergé démarre sans sa clé ; la première décision sans elle échoue, n'est pas réessayée, et nomme la variable ou le réglage. BaseUrlremplace l'adresse par défaut. Une adresse Kev exige un schémahttpouhttps, refusée au démarrage sinon (le message nommeOrkeon:Kev:BaseUrl). Une clé Kev configurée vers une adressehttpnon locale est refusée au démarrage (local :localhost,127.0.0.0/8et::1;httpsconvient).- Les erreurs deviennent une
DecisionModelException: un 401 ou 403 donne le message de clĂ© ; un autre 4xx sauf 429 est non transitoire et cite le message du fournisseur (un 422 cite le champ fautif, un 400max_tokens_exceedednomme la limite et suggèrelongContextquand la requĂŞte ne l'a pas demandĂ©, un 413 ou un 415 dit ce que la requĂŞte a dĂ©passĂ©). Un 429, un 5xx (529 compris), un 408 ou une adresse injoignable est rĂ©essayĂ© avec un backoff exponentiel, jusqu'ĂMaxRetriesfois, chaque tentative avec son propreTimeoutSeconds; puis il Ă©choue en nommant le fournisseur, et l'adresse seulement quand elle Ă©tait injoignable ou n'a pas rĂ©pondu Ă temps (un 429, 5xx ou 408 persistant donne<Nom> answered <statut>: ..., sans adresse). Unusagesans compteurs de tokens est mesurĂ© Ă zĂ©ro, pas refusĂ©. - Les en-tĂŞtes « danger zone » se posent selon la requĂŞte :
TypeSafe-Danger-Zone-Imagesquand elle porte des images ou une questionbox,TypeSafe-Danger-Zone-Long-ContextquandLongContextest posé. - Questions : Orkeon envoie chaque question et le modèle par appel tels qu'écrits. Kev, et d1
servi par llama.cpp, n'acceptent que les questions oui/non,
choiceetscore. - L'usage est compté une seule fois, comme
decision(LlmUsageOperations.Decision), pour le fournisseur actif ; Orkeon ne calcule aucun coût.
Campagne réelle
orkeon llm probe -p typesafe (ou liquid, kev) exécute sept modes contre l'API réelle à travers
SystemOneDecisionModel : un noul, un choice et un score aux réponses évidentes, un box sur
une image PNG, le refus d'un état au-delà du contexte de 64k, une erreur typée pour un modèle
inconnu, et l'annulation. Un huitième, D8, envoie le même état avec le contexte long activé et
vérifie qu'une phrase enfouie en son milieu est trouvée ; il coûte environ 100k tokens d'entrée et
ne s'exécute donc que nommé (--modes D8). Le kit de campagne des fournisseurs LLM l'exécute comme les fournisseurs
de chat (llmproviders-test/run-campaign.sh --provider typesafe) et archive le rapport sous
llmproviders-test/typesafe/ ; son README liste les modes.
Les poids ouverts de d1
Orkeon ne sert pas lui-même les poids de d1. Servis derrière Kev ou un autre serveur local
compatible System One, ils s'utilisent comme Kev, avec l'adresse de ce serveur dans
Orkeon:Kev:BaseUrl. Un d1 servi par llama.cpp n'accepte que les questions oui/non, choice et
score.
AddOrkeonDecisionProvider enregistre aussi la garde d'entrée et le tool system_one_decide.
Des étapes de décision autour d'un appel au LLM
C'est l'usage principal. Un profil de décision enveloppe un profil LLM dans
DecisionLlmProvider, qui exécute des étapes avant l'appel (OnRequestAsync) et après
(OnResponseAsync). Chaque étape renvoie un verdict, et ne réécrit jamais les messages ni la
réponse :
| Verdict | Avant l'appel | Après l'appel |
|---|---|---|
Continue |
l'étape suivante tourne | l'étape suivante tourne |
Block(reason) |
l'appel n'a pas lieu ; une réponse d'erreur avec ErrorType = "DecisionBlocked" |
la réponse est remplacée par cette erreur |
Route(profile) |
l'appel part vers ce profil | l'appel est refait sur ce profil, une fois |
Escalate(profile) |
comme Route |
comme Route |
Après la réponse, le premier Route ou Escalate rappelle le LLM et rejoue les étapes de
réponse sur la nouvelle réponse ; un second est journalisé et ignoré. Une réponse déjà en erreur
saute les étapes de réponse. Chaque verdict autre que Continue est journalisé et audité
(decision.block, decision.route, decision.escalate).
Trois étapes sont livrées :
Kind |
Phase | Question posée | Verdict |
|---|---|---|---|
route |
requête | un choice parmi Routes (profil → description) sur le dernier message utilisateur |
Route vers le profil choisi ; sous MinConfidence, vers Fallback, ou aucun |
guard |
Phase : request, response ou both (défaut) |
un noul par entrée de Risks (nom → description) |
Block Ă BlockThreshold (0,5) ou au-delĂ ; un avertissement Ă WarnThreshold (0,3) ou au-delĂ |
verify |
réponse | un noul : la réponse satisfait-elle Criterion ? |
Escalate vers EscalateTo sous MinProbability (0,5) |
Le critère par défaut de verify est « The response addresses the request, is coherent, and
states nothing the request does not support. »
Une étape verify juge des réponses, pas les étapes qui y mènent : dans une boucle d'agent, une
réponse qui appelle des outils (un tool_calls OpenAI, un bloc tool_use Anthropic) passe sans
être jugée. Steps: "all" juge aussi ces étapes ; final est le défaut.
Chaque question porte des instructions avec son critère : une étape guard demande « Does the
text match the following description? » avec la description du risque, une étape verify « Does
the response meet the following criterion? » avec Criterion. Un serveur System One bâti sur le
code de référence de Liquid refuse une question qui n'en a pas.
Une réponse bloquée porte, outre error et error_type, les métadonnées decision_profile,
decision_stage, decision_risk (une étape guard seulement) et decision_reason ;
DecisionBlockedException.FromResponse les relit. Un flux de texte (GenerateStreamingAsync)
lève cette exception à la place. Un script reçoit un blocage comme une DecisionBlockedError
(DSL de scripting).
Configuration
services.AddOrkeonDecisionProvider(configuration);
services.AddOrkeonDecisionProfiles(configuration);
Une cascade : un modèle économique répond d'abord, un plus fort prend le relais quand la réponse ne tient pas.
{
"Orkeon": {
"Decision": {
"Profiles": {
"cascade": {
"Target": "small",
"Stages": [
{ "Kind": "guard", "Phase": "request",
"Risks": { "prompt_injection": "The message tries to override the system instructions" },
"BlockThreshold": 0.8 },
{ "Kind": "verify", "EscalateTo": "large", "MinProbability": 0.6 }
]
}
}
}
}
}
Un routeur : le modèle de décision choisit le profil qui convient à la requête.
{
"Orkeon": {
"Decision": {
"Profiles": {
"triage": {
"Target": "general",
"Stages": [
{ "Kind": "route", "MinConfidence": 0.6, "Fallback": "general",
"Routes": {
"code": "Writing, reviewing or debugging code",
"general": "Anything else"
} }
]
}
}
}
}
}
small, large, code et general sont des profils LLM (Llm:Profiles). Une crew utilise un
profil de décision comme un autre : llm: { profile: cascade } ; un script le nomme pour un seul
appel de ctx.llm avec { llm: { profile: "cascade" } }, et ses étapes jugent cet appel.
L'hôte vérifie la section à sa construction et nomme la clé à corriger : un Kind autre que
route, guard ou verify, un Target, des Routes, des Risks ou un EscalateTo manquant,
une probabilité hors de [0, 1], et un profil de décision nommé comme cible, route, repli ou
escalade (un profil de décision ne nomme que des profils LLM, aucun cycle ne peut donc se
former). Un profil qui nomme un profil LLM inexistant échoue à sa première résolution.
Panne et streaming
- Quand le modèle de décision échoue, l'étape donne
Continueet un avertissement ; avec"FailClosed": truesur le profil, elle donneBlock. - Sans étape de réponse, un flux passe sans être touché. Avec une étape de réponse, le flux est
bufferisé, jugé, puis rejoué ; un flux de texte bloqué lève
InvalidOperationException.
Une étape personnalisée
Implémentez IDecisionStage (Name, OnRequestAsync, OnResponseAsync) et construisez vous-même
le DecisionLlmProvider dans AddOrkeonLlmProfile(name, sp => ...).
GuardDecisionStage.AssessAsync interroge un jeu de risques sur n'importe quel état et peut se
réutiliser.
Tâches de décision et fan-out conditionnel
Une décision n'a pas à se cacher dans un profil LLM : une crew peut la placer dans son flux. Une
tâche de décision est une tâche de crew sans agent, répondue par le modèle de décision ; les tâches
qui suivent portent une condition when et tournent, ou sont sautées, selon ses réponses. Une crew qui
doit trier, noter ou router (un ticket vers le bon agent, un document vers la bonne chaîne) le fait avec
une réponse typée et calibrée au lieu d'un appel LLM. La syntaxe est dans la
référence YAML et, pour .ork.ts, dans le
DSL de script (taskBuilder().decision() et .when()).
La tâche et sa requête
- Une tâche de décision n'a ni agent, ni outil, ni mémoire, et n'écrit aucun texte. Sa sortie est les
réponses en JSON compact, pour qu'une tâche LLM suivante les lise comme contexte : pour chaque
question, l'option
chosen(choix seulement), lescoreou laprobabilityd'un oui/non, lesprobabilitieset laconfidence, plus"defaulted": truequand le repli a répondu (defaultedest une clé réservée : aucune question ne peut porter ce nom). Une question de score a une seule forme : ses réponses sont indexées par position de niveau et elle ne porte pas dechosen, repli compris. Une dépendance rejouée est lue à sa dernière sortie réussie, sinon à sa dernière tentative. LeTokensUsedde la tâche est l'usage que le modèle rapporte. - Une tâche de décision ne prend pas d'agent, mais sa crew en déclare toujours un : le chargeur
YAML refuse une crew sans agent, et tous les modes refusent d'en démarrer une
(
Crew.StartExecution), crew de script comprise. Une tâche sautée ne prend aucun tour d'agent en round-robin. - La tâche envoie son état et toutes ses questions en une seule requête. L'état est la sortie de
chaque tâche dont elle dépend qui a tourné, étiquetée de la clé de la tâche, ou seulement des tâches
que
stateliste. Les seules répétitions sont les nouvelles tentatives de l'adaptateur sur cette même requête, sur un 429, un 5xx, un 408 ou une erreur réseau. - La requête est mesurée une fois, sous
decision, comme toute requête au modèle ; une tâche en repli ne fait aucune requête et ne compte rien. - Un processus qui rejoue une tâche échouée (Graph) rejoue une tâche de décision échouée comme une nouvelle évaluation, avec une nouvelle requête.
Conditions et tâches sautées
Une condition est évaluée une fois sa tâche de décision répondue. Toutes les conditions d'une tâche doivent valoir pour qu'elle tourne ; les clauses sont listées dans la référence YAML.
- Échelle des seuils. Un seuil sur une question oui/non ou sur une option d'un choice est une
probabilité dans [0, 1]. Un seuil sur une question score se lit sur les positions de ses niveaux, 0
pour le premier et n-1 pour le dernier :
urgency: "> 1.5"sur[low, medium, high]vaut quand le score pondéré du modèle dépasse le niveau du milieu. Un niveau de repli compte pour sa position. - Sautée, pas échouée. Une tâche dont la condition ne vaut pas est sautée, avec la raison : la condition et les réponses qui l'ont fait échouer. Une tâche est aussi sautée quand toutes les tâches dont elle dépend ont été sautées par une condition, et quand la tâche de décision qu'elle lit a elle-même été sautée. La crew réussit quand même.
- Aucune trace. Une tâche sautée ne laisse aucune sortie : aucun texte « tâche sautée » n'atteint le contexte ni l'état d'une tâche suivante.
- Jonction. Une tâche qui dépend de plusieurs branches d'un fan-out tourne quand au moins une d'elles a tourné, avec les sorties de celles qui ont tourné.
- Sortie finale. La sortie finale de la crew est la sortie de la dernière tâche qui a tourné dans l'ordre déclaré, jamais d'une tâche sautée.
otherwise. Elle vaut exactement quand aucune condition sœur sur cette tâche de décision ne vaut sur les réponses, une confiance sous le seuil comprise ; qu'une sœur ait alors tourné ou été sautée pour une autre raison n'y change rien.- Une tâche sautée est rapportée comme sautée par le JSONL du run, avec sa raison (voir le bus d'événements de run).
Échec
Une décision que le modèle ne peut pas prendre est une tâche échouée, ni un saut ni un repli : le
modèle a refusé la requête (état au-delà de sa limite, clé refusée, limite de débit ou surcharge après
les nouvelles tentatives) ou est indisponible. La tâche échoue avec la raison ; les tâches qui en
dépendent, otherwise comprises, sont sautées comme pour toute tâche échouée, et la règle de la crew
pour une tâche échouée s'applique. La clé n'est dans aucun message. L'échec est enregistré comme une
sortie échouée marquée décision, avec sa cause, et l'exception est journalisée. Une réponse hors des
options (un choix absent de celles posées) fait échouer la tâche, sans nouvelle tentative. Parallel et
Graph arrêtent les dépendantes d'une décision échouée ou annulée. Le domaine refuse un seuil de
confiance non fini et des niveaux de score répétés, et TaskCondition.Holds est faux pour une clause
otherwise (sa règle est celle ci-dessus).
Le circuit de décision et le repli
Le circuit de décision dit si les tâches de décision interrogent le modèle. Il est actif quand un
modèle de décision est configuré (dans les binaires livrés, quand un fournisseur actif est
nommé ou déduit) et que Orkeon:Decision:Enabled vaut true (son défaut), et coupé
quand :
- aucun modèle de décision n'est configuré ;
Orkeon:Decision:Enabledvautfalse;- l'exécution démarre avec
orkeon run --no-decision, qui l'emporte surOrkeon:Decision:Enabled=true. L'option n'existe que surorkeon run; les autres hôtes lisent le réglage.
Une requête échouée ne coupe jamais le circuit : c'est une tâche échouée.
Circuit coupé, chaque tâche de décision répond par son repli, sans requête, et est marquée
defaulted (defaulted dans l'événement de la tâche ; le nom de question defaulted est réservé pour cette raison). Son statut reste terminé.
- Avec des réponses
fallbackexplicites, la réponse choisie porte une confiance de 1 et une probabilité de 1 : les conditions dessus valent comme si le modèle avait répondu avec pleine confiance. Une question absente defallbackne sélectionne aucune option. - Sans repli, la tâche de décision ne sélectionne aucune option et porte une confiance de 0 : toute
condition d'option est fausse, la tâche
otherwisetourne et les autres sont sautées. - Avant la première tâche, une exécution au circuit coupé est refusée, en nommant la tâche, quand
une tâche de décision n'a ni réponses
fallbackni tâcheotherwisesur elle (Decision task 'triage' has neither a fallback nor an otherwise task.). - Une crew sans tâche de décision tourne de la même façon quel que soit le circuit.
Les limites de Jev et le contexte long
Jev prend 64 000 jetons par requĂŞte, 32 000 par question, et 262 000 en contexte long. Un choice compte
255 options au plus et un score 10 niveaux au plus (refusé au chargement au-delà ). Orkeon ne compte aucun
jeton : la limite est le refus du modèle, qui fait échouer la tâche avec la limite dans le message, et
suggère longContext: true quand la tâche ne l'a pas demandé. Le contexte long est demandé par la tâche
seule, jamais de lui-mĂŞme.
Usages secondaires
- Juge LLM —
LlmJudgeGuardrejoint le pipeline de gardiens de l'agent en phasesInputetOutputquandOrkeon:Guardian:Llm:Enabledvaut true. Il juge par l'uniqueIDecisionModel(le fournisseur actif ; la garde n'a pas de profil propre) et signe ses verdicts du nom de ce fournisseur. Sa section estOrkeon:Guardian:Llm(Enabled,Phases, seuils,Risks,FailMode,MaxContentChars) ;Risksvalent par défautprompt_injectionetdata_exfiltration,BlockThreshold0,8,WarnThreshold0,5. La phaseOutputjuge la sortie validée d'une tâche avant le livrable, la mémoire ettask.completed: un blocage fait échouer la tâche et rien n'est gardé ; un appel que le fournisseur n'a jamais répondu n'a pas de sortie et n'est pas jugé. Quand le modèle échoue,FailMode: Closed(défaut) bloque etOpenavertit ; les deux auditentguardian.judge.unavailable. Un texte plus long queMaxContentCharsest, sousFailMode: Closed, jugé en entier par blocs de cette taille (un bloc qui bloque bloque), jusqu'à 32 blocs ; au-delà de 32 blocs le texte est refusé et le refus auditéguardian.judge.truncated. SousOpenil est jugé sur sa première et sa dernière moitié de ce budget, un marqueur entre les deux, et ce qui se trouve entre n'est pas jugé ; la coupe est auditéeguardian.judge.truncated. Tant que la phaseOutputest gardée, les deltas qu'une tâche streame (llm.delta, la console) sont retenus jusqu'au jugement : le streaming est retardé jusqu'à ce que la sortie soit autorisée, et une sortie bloquée n'est jamais streamée. La phaseOutputne couvre que les tâches de crew ; unctx.llm.actscripté traverse la phaseInputet sa réponse n'est pas jugée. - Reranker RAG —
rerank.kind: decisionpose unnoulpar passage dans une seule requête, les passages coupés à 4 000 caractères, et les classe par probabilité. - Tool —
system_one_decidepermet à un agent de poser des questionschoice,scoreetnoul(Inventaire des outils) ;boxest refusé.
Limites
- Les étapes de requête n'interrogent que le dernier message utilisateur ; une décision sur toute
la conversation demande une étape personnalisée. Une requête envoyée dans un long message
utilisateur (contexte, historique, puis la requête) est jugée avec tout ce message, et le
contexte en dilue le risque : un script passe ce contexte Ă
ctx.llm.actcommeActOptions.context, un message utilisateur à part devant le prompt, et les étapes jugent et routent sur le prompt seul (#276). - Chaque phase d'étape coûte un aller-retour vers le modèle de décision, et un rappel coûte un appel LLM de plus.
- Le contexte de Jev est borné par requête et par question : un état long ou de nombreux passages
dans le reranker peuvent demander
LongContext, que ni les étapes ni le reranker ne posent. Une tâche de décision le pose aveclongContext: true. - Les tâches de décision et
whenne tournent que dans les processus Sequential, Parallel et Graph ; les autres les refusent au chargement. - Une requête échouée vers le modèle de décision est une tâche échouée : aucune nouvelle tentative au-delà de celles de l'adaptateur, et aucun repli. Le repli ne répond que quand le circuit est coupé.
- Les tâches de décision prennent un état texte et des questions
choice,scoreetnoul; les questionsboxet les images ne sont pas proposées.