mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-18 14:08:21 +00:00
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Vote Gate / Gate (push) Waiting to run
Codegraph E2E Votes / vote (shard 1/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 10/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 2/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 3/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 4/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 5/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 6/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 7/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 8/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 9/10) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions
- A group a layer names that the config below does not serve (one a lower layer's tombstone of a field inside it, or of its groupMap entry, left unable to resolve) gets no key from the YAML-shaped group: a higher layer that re-supplies the field and a new instance or base URL no longer sends librechat.yaml's key there. - /changes and PATCH report unknown_spec_endpoint only where the write touches the spec, so hiding, removing or unsetting the endpoint a profile's stored spec selects is no longer refused; the merge leaves the spec out, as the single-field routes already allowed. - Without CONFIG_REDERIVE_ENDPOINTS, a layer's Azure groups and its tombstones of them (whole, keyed or inside a group) are listed as endpoint_rederive_off in each resolution layer, in GET ignored and in the /changes report. With it, a keyed tombstone that leaves its group unable to resolve is listed as azure_groups_unresolved. Keyed tombstones are located by entry key. - The startup report lists documents whose only Azure override is a keyed group tombstone. - Docs: hides never refused for the specs they take, the new ignored reasons.
189 lines
11 KiB
Markdown
189 lines
11 KiB
Markdown
# Custom endpoints in config profiles
|
|
|
|
Config profiles (the `__base__` document and role, group and user documents written through
|
|
`/api/admin/config`) merge over `librechat.yaml`. `endpoints.custom` merges entry by entry on
|
|
`name`: a profile's entry changes the inherited entry of the same name, and a new name adds an
|
|
endpoint. Names compare as the runtime serves them, so `ollama` in any case is the `Ollama`
|
|
entry.
|
|
|
|
A profile can also take away what a lower layer defined: hide a whole endpoint, remove one of its
|
|
fields, or remove one key of a record map such as `headers`. All three are tombstones that name
|
|
the entry by its key.
|
|
|
|
## Keyed paths
|
|
|
|
A keyed path names one entry of an array merged by key (`rules.arrayMergeKeys` in
|
|
`GET /api/admin/config/meta`, today `endpoints.custom` and `endpoints.azureOpenAI.groups`), then
|
|
optionally a path inside it:
|
|
|
|
```text
|
|
endpoints.custom["<name>"]
|
|
endpoints.custom["<name>"].<field>
|
|
endpoints.custom["<name>"].<record>.<key>
|
|
```
|
|
|
|
`<name>` is a JSON string literal, so any name works: build it with `JSON.stringify(name)`. A name
|
|
may hold dots, spaces, quotes or brackets (`endpoints.custom["api.example.com \"v2\""]`). It may be
|
|
up to `limits.maxEntryKeyLength` (256) characters and may not start with `$` or `__` or be
|
|
`constructor` or `prototype`. The path inside the entry is dotted, so a header name that contains a
|
|
dot cannot be addressed. Tombstones are stored in this canonical form.
|
|
|
|
| Method | Path | Body / query |
|
|
| ------ | ---------------------------------------------------------------- | -------------------------------------------------- |
|
|
| POST | `/api/admin/config/:principalType/:principalId/fields/tombstone` | `{ "fieldPath": "endpoints.custom[\"Name\"]…" }` |
|
|
| DELETE | `/api/admin/config/:principalType/:principalId/fields` | `?fieldPath=` the URL-encoded keyed path |
|
|
| POST | `/api/admin/config/:principalType/:principalId/changes` | `{ "op": "tombstone" \| "unset", "fieldPath": … }` |
|
|
|
|
A keyed path hides or resets; it never writes. Write an entry whole with an `upsertEntry` change,
|
|
or write the `endpoints.custom` array. A keyed path in a PATCH entry, a `set`, or as the collection
|
|
of an entry change answers 400 `CONFIG_PATH_INVALID` with reason `keyed_path`. Only a `fieldPath`
|
|
is read as keyed: a `segments` target names each key as written, so a segment such as
|
|
`custom["Name"]` is a key of that spelling, and a write by it clears none of the entry's
|
|
tombstones.
|
|
|
|
## Hiding an endpoint
|
|
|
|
`fieldPath: 'endpoints.custom["Name"]'` hides the endpoint for every principal the profile applies
|
|
to. The profile's own entry of that name, and any key it stored on it, is removed. Everything that
|
|
offers the endpoint goes with it, so the principals are not offered an endpoint they are not
|
|
served:
|
|
|
|
- the model specs that select it (`preset.endpoint`);
|
|
- its name in `modelSpecs.addedEndpoints`;
|
|
- its name in `endpoints.agents.allowedProviders`.
|
|
|
|
This holds whether `librechat.yaml` or a lower profile (such as `__base__`) defines the endpoint.
|
|
Nothing else goes: when the hidden endpoint selected every spec, the spec list is empty and the
|
|
other `addedEndpoints` stay. An empty `addedEndpoints` or `allowedProviders` allows every endpoint,
|
|
so a list that names only hidden endpoints stays as it is; those names match no endpoint the
|
|
principals are served, so it allows none. With every spec hidden, `modelSpecs.enforce` no longer
|
|
applies, as for a `librechat.yaml` with an empty spec list.
|
|
|
|
A tombstone in the `__base__` profile applies to every principal. Every other profile merges after
|
|
`__base__`.
|
|
|
|
Hiding or removing an endpoint is never refused because the profile's own model specs select it
|
|
(`/changes`, PATCH and the single-field routes alike): those specs go with the endpoint. A write of
|
|
a spec for an endpoint that is not configured answers 400 `unknown_spec_endpoint`, a spec in the
|
|
same batch as the hide included.
|
|
|
|
Hiding is undone by:
|
|
|
|
- deleting the tombstone (`DELETE …/fields?fieldPath=endpoints.custom%5B%22Name%22%5D`);
|
|
- writing the entry again in the same profile, with `upsertEntry` or a write of the
|
|
`endpoints.custom` array (PUT, which replaces the overrides and keeps every tombstone, does not);
|
|
- a higher profile that writes the entry. It gets only what that profile wrote, merged onto nothing,
|
|
so write the complete definition (`baseURL`, `apiKey`, `models` and the rest), as for an endpoint
|
|
that does not exist in `librechat.yaml`.
|
|
|
|
## Removing inherited values
|
|
|
|
`fieldPath: 'endpoints.custom["Name"].<field>'` removes a field a lower layer set, and
|
|
`'endpoints.custom["Name"].headers.<key>'` removes one key of a record map and keeps its siblings.
|
|
This works for `headers`, `addParams` and any other object of the entry:
|
|
|
|
```json
|
|
{ "fieldPath": "endpoints.custom[\"Gateway\"].headers.X-Team" }
|
|
```
|
|
|
|
These tombstones behave as follows:
|
|
|
|
- The profile's own value at the path is removed with it; an own entry left with nothing but its
|
|
name is removed.
|
|
- Writing the entry in the same profile keeps the tombstone. A value the profile writes for the
|
|
same key is used over the tombstone, which keeps hiding the inherited one.
|
|
- `DELETE …/fields?fieldPath=<same path>` removes that tombstone and restores the inherited value.
|
|
- `DELETE …/fields?fieldPath=endpoints.custom["Name"].headers` resets the profile's own headers of
|
|
that entry and the key tombstones under them. A keyed path of the whole entry resets the
|
|
profile's own entry and every keyed tombstone of it, and `fieldPath=endpoints.custom` resets the
|
|
whole list and every keyed tombstone under it.
|
|
- A higher profile can supply the value again.
|
|
|
|
Refused with 400:
|
|
|
|
- the entry's `name`, which identifies it (reason `merge_key`): hide the whole entry instead;
|
|
- `apiKey`, `apiKeyPreview` and the stored destination fingerprint (`SECRET_PATH`): an entry's key
|
|
is entered, kept and removed with the entry;
|
|
- an element of one of the entry's arrays, such as `models.default.0` (`inside_array`): a tombstone
|
|
hides a whole array.
|
|
|
|
A tombstone at a position in the list (`endpoints.custom.0.headers`) is refused too
|
|
(`inside_array`). Before keyed paths, POST `/fields/tombstone` stored it, and the merge never
|
|
applied it.
|
|
|
|
Removing a field the endpoint needs (`baseURL`, `models`) is not reported. The runtime does not
|
|
serve a custom endpoint without them, so it disappears for those principals.
|
|
|
|
## Stored keys
|
|
|
|
A tombstone never sends a key anywhere new:
|
|
|
|
- Hiding a profile's own entry removes the key it stored. Showing the entry again does not bring the
|
|
key back; enter it again.
|
|
- Removing where the profile's own entry sends its stored key (`baseURL`, `provider`, or a
|
|
destination option in `addParams`) answers 400 `CONFIG_SECRET_REENTRY_REQUIRED`, with the
|
|
changed field and `secretPath`, on DELETE, tombstones and `/changes`.
|
|
- Removing it from an inherited entry drops the inherited key at merge, and the write lists the
|
|
key in `ignored` with reason `secret_rebinding`.
|
|
- An inherited endpoint whose users enter their own keys (`user_provided`, `customUserVars`) keeps
|
|
its destination: the merge sets the removed field back and the write lists it in `ignored`.
|
|
|
|
## Renaming
|
|
|
|
A profile renames one of its own entries, with the key stored on it, in either of two ways:
|
|
|
|
- a `rename` change in `/changes`: `{ "op": "rename", "fieldPath": "endpoints.custom", "from":
|
|
"draft", "to": "final" }`;
|
|
- a `renames` hint on PUT or PATCH beside a write of the list that has the entry under its new name
|
|
and not under the old one, without its `apiKey`:
|
|
|
|
```json
|
|
{
|
|
"entries": [{ "fieldPath": "endpoints.custom", "value": [{ "name": "final", "baseURL": "…" }] }],
|
|
"renames": [{ "path": "endpoints.custom", "previousName": "draft", "name": "final" }]
|
|
}
|
|
```
|
|
|
|
Either way, the key keeps its stored ciphertext and preview, and the keyed tombstones of the old
|
|
name move to the new one. The key stays bound to its destination: a renamed entry that sends it
|
|
somewhere else answers 400 `CONFIG_SECRET_REENTRY_REQUIRED`. A key the profile entered for an
|
|
endpoint `__base__` defines keeps the destination fingerprint it was entered with.
|
|
|
|
Entries `librechat.yaml` defines cannot be renamed, and no entry can take their name. A hint that
|
|
cannot apply answers 400 `CONFIG_RENAME_INVALID` with `reason`:
|
|
|
|
| Reason | When |
|
|
| ---------------------- | -------------------------------------------------------------------- |
|
|
| `inherited_entry` | either name is a `librechat.yaml` entry |
|
|
| `source_not_found` | the profile stores no entry named `previousName` |
|
|
| `target_exists` | the profile already stores an entry named `name` |
|
|
| `target_not_written` | the write does not write an entry named `name` |
|
|
| `source_still_written` | the write still writes `previousName`; swap names with `rename` ops |
|
|
| `duplicate_source` | two hints rename the same entry |
|
|
| `duplicate_target` | two hints rename to the same name |
|
|
| `invalid_name` | a name a keyed path cannot address, or two spellings of one entry |
|
|
|
|
Without a hint, a renamed entry is a new entry: it keeps no key, and the tombstones stay on the old
|
|
name.
|
|
|
|
## Azure groups
|
|
|
|
`endpoints.azureOpenAI.groups` merges by `group` the same way (`features.azureGroupMergeKey`) and
|
|
takes the same keyed paths: `endpoints.azureOpenAI.groups["<group>"]` hides an inherited group,
|
|
and `endpoints.azureOpenAI.groups["<group>"].<path>` a field inside one. A group's `apiKey` and its
|
|
preview are written with the group, never by its key. The Azure clients read what the groups
|
|
resolve to, so a hidden group or field takes effect only where the deployment resolves the groups
|
|
a profile leaves (`CONFIG_REDERIVE_ENDPOINTS=true`, `features.endpointRederive`): the groups left
|
|
are resolved again, and a group that no longer resolves once a field inside it is hidden is not
|
|
served; GET of the document and the resolved view list that tombstone in `ignored` with reason
|
|
`azure_groups_unresolved`. A higher profile that writes such a group again gets no key from below
|
|
it: enter the key with the group. Without the switch, the tombstone is stored and inert, as the
|
|
profile's group overrides are, and GET of the document, the resolved view and the `/changes`
|
|
response list each of them in `ignored` with reason `endpoint_rederive_off`.
|
|
|
|
## After upgrading
|
|
|
|
Before keyed paths, a tombstone such as `endpoints.custom["Name"]` was accepted and stored but had
|
|
no effect. Stored ones now hide that entry. Clients send keyed paths only when
|
|
`features.keyedTombstones` is true in `GET /api/admin/config/meta`, and endpoint rename hints when
|
|
`features.renameHints` is.
|