From 11d58e53e93e6f6e7076b33694c074ddf01fff92 Mon Sep 17 00:00:00 2001 From: janiussyafiq Date: Mon, 18 May 2026 20:50:23 +0000 Subject: [PATCH] docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #347. Five corrections, each anchored to a runtime consumer (or non-consumer) verified on `origin/main` at `71ea97e`. The cluster mirrors the consumer-trace discipline locked in by #326 / #344: for every behavioral claim, verify the runtime consumer actually reads the documented value, rather than only verifying the field exists with a default. - admin-api.md:76 — group label "health" → "livez". The public route is `/livez` (registered at crates/aisix-admin/src/lib.rs:67); the `/admin/v1/health` endpoint requires admin auth (registered at :145). - api-keys.md:86 — rotate response example: 16-char suffix replaced with a 32-char suffix. Rotate handler at crates/aisix-admin/src/apikeys_handlers.rs:168 uses `Uuid::new_v4().as_simple()`, which produces 32 hex chars. - caching.md — explicit note that `CachePolicy.backend` is parsed and stored on each row but not consulted at runtime. No consumer of `entry.value.backend` / `policy.backend` / `cache_policy.backend` exists in `crates/`. The proxy uses the bootstrap-config (`cache.backend`) instead. - models.md:80 — `ignore_statuses` default. Field at crates/aisix-core/src/models/model.rs:259-260 (drifted from :159-160 cited in the issue body) is declared `#[serde(default, skip_serializing_if = "Vec::is_empty")] pub ignore_statuses: Vec`, so the actual default is the empty vector — not `[408, 429]` as the doc claimed. Re-presented `[408, 429]` as a recommended explicit setting. Consumer at crates/aisix-proxy/src/background.rs:84,88 calls `cfg.ignore_statuses.contains(...)` against the empty default. - models.md:163 — `Model.cost` consumer split. Standalone OSS proxy hard-codes `cost_usd = 0.0` at crates/aisix-proxy/src/chat.rs:989 (with comment "cp-api recomputes cost server-side from its pricing catalog"). The `Model.cost` field is consumed by AISIX Cloud's cp-api, not by the OSS proxy. --- docs/configuration/admin-api.md | 2 +- docs/configuration/api-keys.md | 2 +- docs/configuration/caching.md | 2 ++ docs/configuration/models.md | 4 ++-- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/configuration/admin-api.md b/docs/configuration/admin-api.md index d864d18d..95a8ea42 100644 --- a/docs/configuration/admin-api.md +++ b/docs/configuration/admin-api.md @@ -73,7 +73,7 @@ The current admin router exposes: Think about these routes in three groups: -- public operator helpers: health, metrics, and OpenAPI discovery +- public operator helpers: livez, metrics, and OpenAPI discovery - CRUD resources: models, API keys, provider keys, guardrails, cache policies, exporters - convenience operator workflow: the in-process playground diff --git a/docs/configuration/api-keys.md b/docs/configuration/api-keys.md index fea6ae43..b8ccb259 100644 --- a/docs/configuration/api-keys.md +++ b/docs/configuration/api-keys.md @@ -83,7 +83,7 @@ Example response shape: "allowed_models": ["gpt-4o-prod"] } }, - "plaintext": "sk-abcd1234ef567890" + "plaintext": "sk-550e8400e29b41d4a716446655440000" } ``` diff --git a/docs/configuration/caching.md b/docs/configuration/caching.md index 8c2fcc9f..b0445d2a 100644 --- a/docs/configuration/caching.md +++ b/docs/configuration/caching.md @@ -82,6 +82,8 @@ Current runtime boundary: - bootstrap config can wire a Redis backend at process start - the dynamic `CachePolicy.backend` field should still be treated conservatively because broader Redis support boundaries are still being expanded +Note: the per-policy `backend` field is currently parsed and stored on the `CachePolicy` row but is not consulted by the runtime proxy. The proxy uses the cache backend selected via bootstrap-config (`cache.backend`) regardless of what each policy specifies. The field is preserved for forward compatibility; do not depend on it to override the runtime backend. + ## Operator Guidance - start with `memory` plus a narrowly scoped policy diff --git a/docs/configuration/models.md b/docs/configuration/models.md index 82cdb47c..a1492284 100644 --- a/docs/configuration/models.md +++ b/docs/configuration/models.md @@ -77,7 +77,7 @@ Current semantics: - only direct models may carry `background_model_check` - routing models reject `background_model_check` -- `ignore_statuses` records the last probe result without marking the model unhealthy; the default ignored set is `[408, 429]` +- `ignore_statuses` records the last probe result without marking the model unhealthy. If omitted, **no** probe statuses are ignored — a 408 or 429 probe response would mark the model unhealthy. Set this field explicitly to skip those statuses. For most deployments, `ignore_statuses: [408, 429]` is a reasonable starting point — it tolerates transient upstream timeouts (408) and rate-limit responses (429) during probes without flapping the model unhealthy. - `stale_after_seconds` is a safety valve for old unhealthy probe state when the checker stops refreshing - `interval_seconds` has a minimum of `5`; `timeout_seconds`, `max_tokens`, and `stale_after_seconds` have a minimum of `1` @@ -160,7 +160,7 @@ curl -sS -X POST http://127.0.0.1:3001/admin/v1/models \ - `provider` currently supports `openai`, `anthropic`, `google`, `deepseek`, `cohere`, and `jina`. - `provider_key_id` must reference an existing `ProviderKey` resource. - `timeout` is in milliseconds. `0` or omission means no timeout. -- `cost` stores pricing metadata used by budget and usage accounting paths. +- `cost` stores pricing metadata. AISIX Cloud's cp-api recomputes cost server-side from its pricing catalog when emitting usage events and consumes this field at that layer. The standalone OSS proxy does not consult this field at request time and always emits `cost_usd=0.0` in its own usage events; pricing-aware budget enforcement requires the AISIX Cloud control plane. - `background_model_check` drives direct-model runtime unhealthy state and the `/admin/v1/models/status` view. - `cooldown` drives direct-model request-path cooldown and is also surfaced through `/admin/v1/models/status`.