99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# Hermes Relay v3.3
|
|
|
|
Snelle Quart-bridge tussen Node-RED en een warme Hermes Agent.
|
|
|
|
```text
|
|
Node-RED ──POST /ask──▶ Quart relay ──serialized call──▶ warme Hermes-agent
|
|
│
|
|
└── JSON direct terug naar Node-RED
|
|
|
|
Optioneel: Telegram-bezorging via `hermes send` (standaard uit)
|
|
```
|
|
|
|
## Gedrag en grenzen
|
|
|
|
- **Warme agent:** Hermes wordt tijdens startup geladen/geïnitialiseerd.
|
|
- **Veilige concurrency:** de gedeelde, mutable agent verwerkt precies één LLM-call tegelijk. Overige HTTP-verzoeken wachten in de queue; ze kunnen niet elkaars `messages` resetten.
|
|
- **Timeout:** `HERMES_RELAY_TIMEOUT` (standaard 120 s) omvat wachttijd plus LLM-call. Een timeout retourneert HTTP `504`.
|
|
- **Snelle response:** Een succesvolle `/ask` reageert zodra het model antwoordt.
|
|
- **Geen chatbezorging standaard:** relay-antwoorden blijven in de HTTP-response en verschijnen dus niet in Telegram.
|
|
- **Optionele Telegram-bezorging:** alleen met `HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED=true` wordt het antwoord asynchroon via `hermes send` bezorgd. Bij een gecontroleerde shutdown wacht de service op lopende bezorgingen.
|
|
|
|
## Endpoints
|
|
|
|
### `POST /ask`
|
|
|
|
JSON body:
|
|
|
|
```json
|
|
{ "payload": "Wat is het weer in Best?" }
|
|
```
|
|
|
|
Succesresponse:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"answer": "...",
|
|
"elapsed_seconds": 6.213,
|
|
"llm_elapsed_seconds": 6.213,
|
|
"request_elapsed_seconds": 6.214,
|
|
"telegram_queued": false
|
|
}
|
|
```
|
|
|
|
`elapsed_seconds` blijft aanwezig voor compatibiliteit en is de LLM-duur. `request_elapsed_seconds` is de feitelijke HTTP-duur. `telegram_queued` is standaard `false`; bij expliciet ingeschakelde Telegram-bezorging betekent `true` dat de achtergrondtaak is ingepland. Raadpleeg dan journald voor het uiteindelijke bezorgresultaat.
|
|
|
|
Fouten: `400` lege payload, `413` payload groter dan limiet, `504` timeout, `502` onverwachte agentfout.
|
|
|
|
### `GET /health`
|
|
|
|
Geeft service-status, versie en het aantal lopende Telegram-bezorgingen terug.
|
|
|
|
- `/health?detail=true` voegt de **lokale agent-state** toe; dit doet bewust geen dure LLM/provider-call.
|
|
|
|
## Configuratie
|
|
|
|
| Variabele | Standaard | Betekenis |
|
|
|---|---:|---|
|
|
| `HERMES_RELAY_TIMEOUT` | `120` | Max. wachttijd + modelcall per HTTP-request |
|
|
| `HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED` | `false` | Zet alleen op `true` voor asynchrone Telegram-bezorging |
|
|
| `HERMES_RELAY_DELIVERY_WORKERS` | `2` | Begrensde workers voor Telegram-bezorging als die is ingeschakeld |
|
|
| `HERMES_RELAY_MAX_PAYLOAD_CHARS` | `12000` | Maximale lengte van `payload` |
|
|
| `HERMES_RELAY_MAX_TURNS` | `10` | Agent turn-budget |
|
|
| `HERMES_RELAY_MODEL` | profieldefault | Optionele modelovertuiging |
|
|
| `HERMES_RELAY_TOOLSETS` | leeg | Alleen invullen met geldige benodigde toolsets |
|
|
|
|
De relay leest zijn Hermes-config via profiel `voice-assistant`. Pas model/provider/config aan en herstart daarna de service:
|
|
|
|
```bash
|
|
systemctl restart hermes-relay
|
|
```
|
|
|
|
## Testen
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:8650/health
|
|
curl -s -X POST http://127.0.0.1:8650/ask \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"payload":"Zeg alleen hoi"}'
|
|
|
|
journalctl -u hermes-relay -f
|
|
```
|
|
|
|
## Node-RED
|
|
|
|
Gebruik een HTTP Request-node:
|
|
|
|
- **Method:** `POST`
|
|
- **URL:** `http://192.168.1.74:8650/ask`
|
|
- **Return:** parsed JSON
|
|
- **Timeout:** `120000` ms
|
|
|
|
Voorafgaande Function-node:
|
|
|
|
```javascript
|
|
msg.payload = { payload: msg.payload };
|
|
return msg;
|
|
```
|