Model backend administration objects and rules¶
Manage LLM/Embedding backends, access endpoints, and routing in the current Workspace. Root-level and Workspace-level protocols access the same kinds of owner, but differ in fields, defaults, envelopes, and successful HTTP statuses.
Before you call this API¶
BASE_URL, MOI_KEY, and WORKSPACE_ID come from the same environment. Obtain BACKEND_ID/ENDPOINT_ID from reads in that environment and the same kind. Provider credential provider-key-example and URLs are placeholders; replace them before actual calls. Production deployment support requires separate confirmation.
Root-level /llm and /embedding select the tenant through X-Workspace-ID; they are not global administrator configuration. Workspace-level /workspaces/{id}/llm and /embeddings select the Workspace in the path. Ordinary product authentication and validated task identities are handled separately. These examples use ordinary identities and do not establish acceptance of the full task-calling flow.
Canonical backend identity includes kind and numeric ID. The same integer may belong to different kinds and cannot be reused across them. Administration paths accept only canonical positive decimal IDs; 0, negatives, leading zeroes, and plus signs are rejected. Synthetic negative system identities in model lists cannot be used directly for these operations.
Task |
Permission |
|---|---|
Backend collection/details and endpoint collection |
model_backend.read; collections are filtered by the currently effective role. |
Create backend |
Workspace model_backend.create; creation results are associated with the Ownership lifecycle. |
Update backend, create endpoint, or write status |
model_backend.update on the specified backend. |
Delete backend |
model_backend.delete on the specified backend, entering the deletion lifecycle. |
Read/write Router |
Workspace model_router.read / model_router.update. |
Model execution has no separate model_backend.use permission. Actual Agent/task/data access follows its own formal admission boundaries. Reading configuration or modifying a Router does not grant actual inference, data, or paid-resource access.
Response structures¶
Item |
Root-level |
Workspace-level |
|---|---|---|
Success envelope |
code=”OK”, msg=”OK”, data |
code=0, data; 204 has no response body. |
Backend list |
data.backends, possibly null; no total |
data.backends and total; empty fields may be omitted. |
Backend object |
data directly contains the backend and may include endpoints |
data directly contains the backend, omits zero-valued fields, and does not include endpoints. |
Endpoint list |
data.endpoints, possibly null |
data is directly an array, [] when empty. |
Router |
data directly contains the configuration |
data.config contains the configuration. |
Create backend/endpoint |
HTTP 200 |
HTTP 201。 |
Delete backend |
HTTP 200,data.success=true |
LLM 204;Embedding 200,data.deleted=true。 |
Set endpoint status |
HTTP 200,data.success=true |
LLM 204;Embedding 200,data.updated=true。 |
Backend fields¶
Field |
Type |
Description |
|---|---|---|
id |
integer |
Backend ID within the current kind. |
name |
string |
Backend name. |
type |
string or integer |
String for root-level; numeric for Workspace-level. |
timeout_seconds |
integer |
Configured timeout in seconds. |
models |
array (strings) |
Declared model names. May be null for root-level or omitted when empty for Workspace-level. |
reasoning_control_protocol |
string or integer |
LLM reasoning-control protocol; fixed NONE/0 for Embedding. |
created_at |
integer |
Unix seconds. Zero times may be omitted for Workspace-level. |
updated_at |
integer |
Unix seconds. Zero times may be omitted for Workspace-level. |
endpoints |
array (objects) |
May appear in root-level reads. LLM includes online entries only; Embedding retains both states. Update results omit it. |
api_key_encrypted |
string |
Workspace-level write results may return saved values; lists/details actively remove them. |
provider_origin |
string |
Workspace-level source. LLM accepts external_provider; Embedding returns unknown. |
origin_ref |
string |
Workspace-level LLM source reference; omitted when empty. |
origin_version |
string |
Workspace-level LLM source version; omitted when empty. |
Root-level responses do not return credentials. Workspace-level creation/updates use an unredacted converter, so nonempty saved values may appear in api_key_encrypted. Lists/details use a redacted converter and omit it. The field name does not establish encryption or automatic client-side encryption. Use placeholders only in examples and records.
Workspace-level backend type maps 0 OPENAI, 1 OLLAMA, 2 VLLM, 3 QIANWEN, 4 DOUBAO, 5 DEV_LLM, and 6 HTTP. Embedding creation rejects DEV_LLM. Configuration acceptance does not establish production routing support. Generic LoadLLMWorkspaceConfig rejects DEV_LLM/HTTP; chat uses LoadChatCompletionWorkspaceConfig, which allows DEV_LLM but rejects HTTP. Do not conflate these loaders or treat development adapters as production support.
Workspace-level LLM reasoning control values 0–5 map to NONE, OPENAI_REASONING_EFFORT, CHAT_TEMPLATE_KWARGS_ENABLE_THINKING, CHAT_TEMPLATE_KWARGS_THINKING, OLLAMA_THINK, and QIANWEN_ENABLE_THINKING. Root-level accepts corresponding names and official REASONING_CONTROL_* strings. Actual model support requires separate testing.
Endpoint fields¶
Field |
Type |
Description |
|---|---|---|
id |
integer |
Endpoint ID. |
backend_id |
integer |
Owning backend ID. |
address |
string |
Access URL. |
status |
string or integer |
Root-level ONLINE/OFFLINE; Workspace-level 0/1. |
created_at |
integer |
Unix seconds. |
updated_at |
integer |
Unix seconds. |
LLM endpoint lists, backend lists, and backend details filter out offline entries; Embedding retains both states. Save an endpoint’s creation ID before setting it offline: these reads cannot retrieve offline LLM endpoint IDs afterward. Workspace-level status=0 may be omitted in HTTP, while the SDK default remains online; omission does not mean unknown. Online/offline changes configuration, without testing health or deleting endpoints.
Router fields¶
Root-level field |
Workspace-level field |
Type/meaning |
|---|---|---|
strategy |
strategy |
ROUND_ROBIN/LEAST_CONNECTIONS/MODEL_BASED strings, or corresponding integers 0/1/2. |
health_check_interval |
health_check_interval_seconds |
Positive seconds. |
max_retries |
max_retries |
Retry configuration; see the comparison page for protocol-specific defaults. |
session_affinity |
enable_session_affinity |
boolean. Omission/null writes false. |
None |
id |
Configuration record ID; omitted when zero. |
None |
created_at |
Unix seconds; omitted when zero. |
None |
updated_at |
Unix seconds; omitted when zero. |
Router PUT writes complete configuration. Unspecified fields do not preserve old values. Owner reads return defaults when the configuration row is absent, while DAO writes update existing records instead of creating them. Real missing-row behavior requires separate verification; reading defaults does not establish initialization. Back up before writing, read back afterward, and verify routing using real model requests. Recover and clean up only within the same environment.
Errors and result confirmation¶
Root-level uses string code/msg; Workspace-level uses integer code/message. Invalid parameters/enums and missing objects may return 400/404 respectively; authorization rejection uses 403 and dependency failure 503. Other mappings depend on the entry point. Invalid root-level reasoning protocols may return 500/ErrServer, while invalid Workspace-level numbers are rejected during binding/mapping. Do not reuse one error table for both.
Embedding DAO handling of zero matches for deletion or endpoint status differs from LLM. Formal IAM/object lifecycle checks may reject requests before the DAO. Storage branches do not establish public API idempotency or success for arbitrary missing IDs. The specification requires stable reference-conflict errors, but complete reference admission still needs review; do not assume deletion has no effects.
Request binding does not uniformly reject unknown keys or trailing JSON. Confirm field acceptance, HTTP success, SDK decoding, and actual target value changes separately.