Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(custom): per-endpoint identity for relay models (#659)

Tashfeene0befba53c06
diff --git a/client/src/components/model-table.tsx b/client/src/components/model-table.tsx
index a42a4d21..21dd90c7 100644
--- a/client/src/components/model-table.tsx
+++ b/client/src/components/model-table.tsx
@@ -11,6 +11,8 @@ import {
formatContext,
groupMaxContext,
groupQuotaBadge,
+ memberEndpointTitle,
+ memberProviderLabel,
providerLabel,
type ModelGroupRow,
type Row,
@@ -125,12 +127,21 @@ export function RowContent({
draggable,
dragHandle,
onToggle,
+ providerName,
+ providerTitle,
}: {
row: Row
rank: number
draggable: boolean
dragHandle?: ReactNode
onToggle: (modelDbId: number, enabled: boolean) => void
+ // Overrides the provider label — the model page passes an endpoint-qualified
+ // one when two custom endpoints serve this same model id (#651).
+ providerName?: string
+ // Hover text for that label, supplied ONLY when the caller actually had to
+ // disambiguate. Never derived from row.endpointScope here: every custom row
+ // carries a scope, so doing so would leak the base URL of a lone endpoint.
+ providerTitle?: string
}) {
const { t } = useI18n()
const guard = (row.headroom ?? 1) * (row.rateLimit ?? 1)
@@ -143,7 +154,9 @@ export function RowContent({
<td className="py-2 pr-3 align-middle">
<div className="flex items-center gap-2 flex-wrap">
<span className="font-medium text-sm">{row.displayName}</span>
- <span className="text-xs text-muted-foreground">{providerLabel(row)}</span>
+ <span className="text-xs text-muted-foreground" title={providerTitle}>
+ {providerName ?? providerLabel(row)}
+ </span>
{row.supportsVision && (
<span
title={t('models.visionTitle')}
@@ -218,11 +231,15 @@ export const dragDots = (
// The collapsed header row for a logical-model group: name, provider count,
// union vision/tools badges, the best member's axis bars + score, and a single
// switch that enables/disables every provider in the group.
-export function GroupHeaderCells({ group, rank, dragHandle, onToggleGroup }: {
+export function GroupHeaderCells({ group, rank, dragHandle, onToggleGroup, allRows }: {
group: ModelGroupRow
rank: number
dragHandle?: ReactNode
onToggleGroup: (memberIds: number[], enabled: boolean) => void
+ // Every configured row, for endpoint disambiguation. Two relays serving one
+ // model id land in different display groups the moment one copy is renamed,
+ // so the group's own members are not a complete sibling set (#651).
+ allRows?: readonly Row[]
}) {
const { t } = useI18n()
const anyEnabled = group.members.some(m => m.enabled)
@@ -235,9 +252,10 @@ export function GroupHeaderCells({ group, rank, dragHandle, onToggleGroup }: {
// its range spans every member. The score cell keeps the best member's score
// (that is what routing would pick) but labels it "best of N" with the
// per-provider breakdown in a tooltip.
+ const siblings = allRows ?? group.members
const measured = group.members.filter(m => (m.totalRequests ?? 0) > 0)
const scoreBreakdown = group.members
- .map(m => `${providerLabel(m)} ${m.score !== undefined ? m.score.toFixed(3) : '–'}`)
+ .map(m => `${memberProviderLabel(m, siblings)} ${m.score !== undefined ? m.score.toFixed(3) : '–'}`)
.join(' · ')
const vision = group.members.some(m => m.supportsVision)
const tools = group.members.some(m => m.supportsTools)
@@ -257,8 +275,8 @@ export function GroupHeaderCells({ group, rank, dragHandle, onToggleGroup }: {
<Link to={`/models/chat/${detailId}`} aria-label={t('models.viewProviders')} onClick={e => e.stopPropagation()} className="flex items-center gap-2 flex-wrap text-left min-w-0">
<span className="font-medium text-sm">{group.label}</span>
{solo
- ? <span className="text-xs text-muted-foreground">{providerLabel(group.members[0])}</span>
- : <Tooltip text={t('models.servedBy', { providers: group.members.map(m => providerLabel(m)).join(', ') })}>
+ ? <span className="text-xs text-muted-foreground" title={memberEndpointTitle(group.members[0], siblings)}>{memberProviderLabel(group.members[0], siblings)}</span>
+ : <Tooltip text={t('models.servedBy', { providers: group.members.map(m => memberProviderLabel(m, siblings)).join(', ') })}>
<span className="text-[10px] rounded-full px-1.5 py-0.5 bg-muted text-muted-foreground">{t('models.providerCount', { count: group.members.length })}</span>
</Tooltip>}
{quota && (
@@ -312,10 +330,11 @@ export function GroupHeaderCells({ group, rank, dragHandle, onToggleGroup }: {
)
}
-export function SortableGroupRow({ group, rank, onToggleGroup }: {
+export function SortableGroupRow({ group, rank, onToggleGroup, allRows }: {
group: ModelGroupRow
rank: number
onToggleGroup: (memberIds: number[], enabled: boolean) => void
+ allRows?: readonly Row[]
}) {
const { t } = useI18n()
const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: `grp:${group.key}` })
@@ -340,7 +359,7 @@ export function SortableGroupRow({ group, rank, onToggleGroup }: {
onClick={() => navigate(`/models/chat/${detailId}`)}
className={`group/row border-b last:border-0 bg-card cursor-pointer transition-colors hover:[&>td]:bg-muted/50 [&>td:first-child]:rounded-l-lg [&>td:last-child]:rounded-r-lg ${isDragging ? 'opacity-50' : ''} ${anyEnabled ? '' : 'opacity-50'}`}
>
- <GroupHeaderCells group={group} rank={rank} dragHandle={handle} onToggleGroup={onToggleGroup} />
+ <GroupHeaderCells group={group} rank={rank} dragHandle={handle} onToggleGroup={onToggleGroup} allRows={allRows} />
</tr>
)
}
diff --git a/client/src/lib/routing.test.ts b/client/src/lib/routing.test.ts
new file mode 100644
index 00000000..8af8e3f5
--- /dev/null
+++ b/client/src/lib/routing.test.ts
@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest'
+import {
+ isMemberSplit,
+ memberEndpointTitle,
+ memberOverrideKey,
+ memberProviderLabel,
+ providerPinId,
+ splitsWithoutMember,
+} from './routing'
+
+// Per-endpoint identity must be INVISIBLE until two endpoints actually serve the
+// same model id (#651). The server sends `endpointScope` / `qualifiedModelId` on
+// every custom row — including the only relay of a one-endpoint install — so any
+// gate written against those fields alone leaks the user's own base URL. These
+// cases pin the gate to the collision itself.
+
+type R = {
+ platform: string; modelId: string; source?: 'catalog' | 'custom'
+ keyLabel?: string | null; endpointScope?: string | null; qualifiedModelId?: string | null
+ displayName?: string
+}
+
+const soloRelay: R = {
+ platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Custom',
+ endpointScope: 'http://192.168.1.50:11434/v1',
+ qualifiedModelId: 'custom:deepseek-v3.1#192.168.1.50-11434-v1',
+}
+const relayA: R = {
+ platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Relay A',
+ endpointScope: 'https://relay-a.example.com/v1',
+ qualifiedModelId: 'custom:deepseek-v3.1#relay-a.example.com-v1',
+}
+const relayB: R = {
+ platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Relay B',
+ endpointScope: 'https://relay-b.example.com/v1',
+ qualifiedModelId: 'custom:deepseek-v3.1#relay-b.example.com-v1',
+}
+const catalog: R = { platform: 'groq', modelId: 'llama-3.3-70b', source: 'catalog' }
+
+describe('single-endpoint install stays un-qualified', () => {
+ it('labels the lone relay by its key label only', () => {
+ expect(memberProviderLabel(soloRelay, [soloRelay])).toBe('Custom')
+ })
+
+ it('reveals no endpoint URL on hover', () => {
+ expect(memberEndpointTitle(soloRelay, [soloRelay])).toBeUndefined()
+ })
+
+ it('offers the bare model id, never the qualified one', () => {
+ expect(providerPinId(soloRelay, [soloRelay])).toBe('deepseek-v3.1')
+ })
+
+ it('leaves catalog rows entirely alone', () => {
+ expect(memberProviderLabel(catalog, [catalog, soloRelay])).toBe('groq')
+ expect(memberEndpointTitle(catalog, [catalog, soloRelay])).toBeUndefined()
+ })
+})
+
+describe('two endpoints serving one model id', () => {
+ const both = [relayA, relayB]
+
+ it('appends the endpoint to each label', () => {
+ expect(memberProviderLabel(relayA, both)).toBe('Relay A · relay-a.example.com/v1')
+ expect(memberProviderLabel(relayB, both)).toBe('Relay B · relay-b.example.com/v1')
+ })
+
+ it('reveals the full endpoint URL on hover', () => {
+ expect(memberEndpointTitle(relayA, both)).toBe('https://relay-a.example.com/v1')
+ expect(memberEndpointTitle(relayB, both)).toBe('https://relay-b.example.com/v1')
+ })
+
+ it('offers the qualified id so a copy pins one relay', () => {
+ expect(providerPinId(relayA, both)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
+ expect(providerPinId(relayB, both)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
+ })
+
+ it('does not disambiguate a DIFFERENT model id that only one relay serves', () => {
+ const soloOnA: R = { ...relayA, modelId: 'qwen-3' }
+ const siblings = [soloOnA, relayA, relayB]
+ expect(memberProviderLabel(soloOnA, siblings)).toBe('Relay A')
+ expect(memberEndpointTitle(soloOnA, siblings)).toBeUndefined()
+ expect(providerPinId(soloOnA, siblings)).toBe('qwen-3')
+ })
+})
+
+
+// Display name is presentation, never identity (#651). Renaming one relay's copy
+// moves it into a different display-name group, but the two rows still share
+// (platform, model_id) — so the disambiguation must key on that pair and nothing
+// else, and the split/merge override must name ONE relay's row.
+describe('two endpoints whose copies were renamed apart', () => {
+ const renamedA: R = { ...relayA, displayName: 'DeepSeek via A' }
+ const all = [renamedA, relayB]
+
+ it('still labels each with its endpoint', () => {
+ expect(memberProviderLabel(renamedA, all)).toBe('Relay A · relay-a.example.com/v1')
+ expect(memberProviderLabel(relayB, all)).toBe('Relay B · relay-b.example.com/v1')
+ })
+
+ it('still hands out the qualified id to copy', () => {
+ expect(providerPinId(renamedA, all)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
+ expect(providerPinId(relayB, all)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
+ })
+
+ it('still reveals the endpoint on hover', () => {
+ expect(memberEndpointTitle(renamedA, all)).toBe('https://relay-a.example.com/v1')
+ })
+})
+
+describe('split / merge override key', () => {
+ it('names one relay\'s row, not every custom row with that model id', () => {
+ expect(memberOverrideKey(relayA)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
+ expect(memberOverrideKey(relayB)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
+ expect(memberOverrideKey(relayA)).not.toBe(memberOverrideKey(relayB))
+ })
+
+ it('keeps the plain member id for rows with no endpoint of their own', () => {
+ expect(memberOverrideKey(catalog)).toBe('groq:llama-3.3-70b')
+ expect(memberOverrideKey({ platform: 'custom', modelId: 'legacy' })).toBe('custom:legacy')
+ })
+})
+
+describe('collision detection keys on (platform, model_id)', () => {
+ it('ignores a same-id row on a different platform', () => {
+ const sameIdOnCatalog: R = { platform: 'groq', modelId: 'deepseek-v3.1', source: 'catalog' }
+ expect(memberProviderLabel(soloRelay, [soloRelay, sameIdOnCatalog])).toBe('Custom')
+ expect(providerPinId(soloRelay, [soloRelay, sameIdOnCatalog])).toBe('deepseek-v3.1')
+ })
+})
+
+// A split persisted BEFORE per-endpoint identity names the row in the plain
+// "platform:modelId" form. The override key is qualified now, so a naive
+// equality check stops recognising it: the row stays split with no control to
+// merge it back. Rewriting the stored key would be a silent data migration for
+// a cosmetic gain, so matching has to accept both forms instead.
+describe('pre-#651 split overrides stay undoable', () => {
+ const legacySplit = [{ member: 'custom:deepseek-v3.1' }]
+ const qualifiedSplit = [{ member: 'custom:deepseek-v3.1#relay-a.example.com-v1' }]
+
+ it('recognises a split stored in the plain form', () => {
+ expect(isMemberSplit(legacySplit, relayA)).toBe(true)
+ })
+
+ it('recognises one stored in the qualified form', () => {
+ expect(isMemberSplit(qualifiedSplit, relayA)).toBe(true)
+ })
+
+ it('removes the entry that is actually stored, whichever form it uses', () => {
+ expect(splitsWithoutMember(legacySplit, relayA)).toEqual([])
+ expect(splitsWithoutMember(qualifiedSplit, relayA)).toEqual([])
+ })
+
+ it('does not treat a sibling relay as split by the other one\'s entry', () => {
+ expect(isMemberSplit(qualifiedSplit, relayB)).toBe(false)
+ expect(splitsWithoutMember(qualifiedSplit, relayB)).toEqual(qualifiedSplit)
+ })
+
+ it('still matches a plain entry on a row that has no endpoint at all', () => {
+ const legacyRow = { platform: 'custom', modelId: 'legacy', source: 'custom' as const }
+ expect(isMemberSplit([{ member: 'custom:legacy' }], legacyRow)).toBe(true)
+ })
+
+ it('leaves catalog rows on the plain form only', () => {
+ expect(isMemberSplit([{ member: 'groq:llama-3.3-70b' }], catalog)).toBe(true)
+ })
+})
diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.ts
index 88757cfb..b8275f1e 100644
--- a/client/src/lib/routing.ts
+++ b/client/src/lib/routing.ts
@@ -31,6 +31,14 @@ export interface FallbackEntry {
source?: 'catalog' | 'custom'
keyId?: number | null
keyLabel?: string | null
+ // Which custom endpoint this row belongs to (its base URL), and the model id
+ // that names this endpoint's copy on its own. Null for catalog models only:
+ // EVERY custom row bound to an endpoint carries both, including the single
+ // relay of a one-endpoint install. Neither may be rendered directly —
+ // go through memberProviderLabel / providerPinId / memberEndpointTitle, which
+ // reveal them only once two endpoints actually collide (#651).
+ endpointScope?: string | null
+ qualifiedModelId?: string | null
hasOverrides?: boolean
// Which fields a local override replaces, so the model page can mark the
// individual inputs that no longer show the catalog default (#551).
@@ -88,6 +96,120 @@ export function providerLabel(row: { platform: string; source?: 'catalog' | 'cus
return row.platform
}
+// Two custom endpoints can now each serve the same model id (#651). Short
+// host-ish form of an endpoint URL, used only to tell those two apart.
+export function endpointShortLabel(scope: string): string {
+ return scope.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/\/+$/, '')
+}
+
+/**
+ * The provider label for one row of a group, disambiguated ONLY when it has to
+ * be: another row in the same group serves the same model id from a DIFFERENT
+ * endpoint. Then the endpoint's URL is appended, because that — not the key
+ * label, which defaults to a generic "Custom" and is not required to be unique
+ * — is what actually tells the two relays apart. Every catalog model, and every
+ * install with a single custom endpoint, gets exactly the label it got before,
+ * so there is nothing new to notice until a real collision exists.
+ */
+export function memberProviderLabel<T extends {
+ platform: string; modelId: string; source?: 'catalog' | 'custom'
+ keyLabel?: string | null; endpointScope?: string | null
+}>(row: T, siblings: readonly T[]): string {
+ const base = providerLabel(row)
+ if (row.source !== 'custom' || !row.endpointScope) return base
+ if (!hasEndpointCollision(row, siblings)) return base
+ return `${base} · ${endpointShortLabel(row.endpointScope)}`
+}
+
+/**
+ * Whether another row shares this row's (platform, model_id) from a DIFFERENT
+ * endpoint. Deliberately keyed on that pair alone: display name is presentation
+ * (renaming one relay's copy moves it to another group but changes nothing about
+ * identity), and a same-id row on another platform is already told apart by its
+ * platform. Callers must pass EVERY configured row, not one display group's
+ * members, or a renamed sibling goes unseen and the endpoint is hidden exactly
+ * when it is needed (#651).
+ */
+function hasEndpointCollision<T extends {
+ platform: string; modelId: string; source?: 'catalog' | 'custom'; endpointScope?: string | null
+}>(row: T, siblings: readonly T[]): boolean {
+ if (row.source !== 'custom' || !row.endpointScope) return false
+ const endpoints = new Set(siblings
+ .filter(s => s.platform === row.platform && s.modelId === row.modelId
+ && s.source === 'custom' && !!s.endpointScope)
+ .map(s => s.endpointScope))
+ return endpoints.size > 1
+}
+
+/**
+ * The full endpoint URL to reveal on hover, or undefined when there is nothing
+ * to disambiguate. Gated on the SAME collision test as the visible label rather
+ * than on `endpointScope` alone — every custom row carries a scope, so gating on
+ * the field itself would pop a tooltip with the user's own base URL on a
+ * single-endpoint install, which is exactly what #651 must not do.
+ */
+export function memberEndpointTitle<T extends {
+ platform: string; modelId: string; source?: 'catalog' | 'custom'
+ keyLabel?: string | null; endpointScope?: string | null
+}>(row: T, siblings: readonly T[]): string | undefined {
+ if (memberProviderLabel(row, siblings) === providerLabel(row)) return undefined
+ return row.endpointScope ?? undefined
+}
+
+/**
+ * The id to send when you want THIS provider's copy. The bare model id, as
+ * always — except when two custom endpoints in the group serve it, where only
+ * the endpoint-qualified id the server computed names one of them.
+ */
+export function providerPinId<T extends {
+ platform: string; modelId: string; source?: 'catalog' | 'custom'
+ endpointScope?: string | null; qualifiedModelId?: string | null
+}>(row: T, siblings: readonly T[]): string {
+ if (!row.qualifiedModelId) return row.modelId
+ return hasEndpointCollision(row, siblings) ? row.qualifiedModelId : row.modelId
+}
+
+/**
+ * The member id a unify split/merge override should be written against. Unlike
+ * the ids shown to users, this is ALWAYS the qualified form for a row that has
+ * an endpoint: an override is persisted state, so it has to keep naming the same
+ * row even after the sibling that caused the collision is removed. The server
+ * matches the plain member id too, so overrides written before #651 still apply.
+ */
+export function memberOverrideKey(row: {
+ platform: string; modelId: string; qualifiedModelId?: string | null
+}): string {
+ return row.qualifiedModelId ?? `${row.platform}:${row.modelId}`
+}
+
+type OverrideRow = { platform: string; modelId: string; qualifiedModelId?: string | null }
+type SplitEntry = { member: string; groupKey?: string }
+
+/**
+ * Every persisted form that names this row: the qualified id written since #651,
+ * and the plain "platform:modelId" that overrides saved before it use. Matching
+ * both is what keeps an existing split undoable — the alternative, rewriting
+ * stored keys on read, is a silent data migration for a cosmetic gain.
+ */
+function overrideKeyAliases(row: OverrideRow): string[] {
+ const plain = `${row.platform}:${row.modelId}`
+ return row.qualifiedModelId && row.qualifiedModelId !== plain
+ ? [row.qualifiedModelId, plain]
+ : [plain]
+}
+
+/** Whether a persisted split names this row, in either form. */
+export function isMemberSplit(splits: readonly SplitEntry[], row: OverrideRow): boolean {
+ const aliases = overrideKeyAliases(row)
+ return splits.some(s => aliases.includes(s.member))
+}
+
+/** The splits list with this row's entry dropped, whichever form it was saved in. */
+export function splitsWithoutMember(splits: readonly SplitEntry[], row: OverrideRow): SplitEntry[] {
+ const aliases = overrideKeyAliases(row)
+ return splits.filter(s => !aliases.includes(s.member))
+}
+
export function formatTokens(n: number): string {
if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsx
index d3ec9a85..bd3a2574 100644
--- a/client/src/pages/FallbackPage.tsx
+++ b/client/src/pages/FallbackPage.tsx
@@ -371,7 +371,7 @@ export default function FallbackPage() {
<SortableContext items={renderedGroups.map(g => `grp:${g.key}`)} strategy={verticalListSortingStrategy}>
<tbody>
{renderedGroups.map(g => (
- <SortableGroupRow key={g.key} group={g} rank={rankByKey.get(g.key) ?? 0} onToggleGroup={handleGroupToggle} />
+ <SortableGroupRow key={g.key} group={g} rank={rankByKey.get(g.key) ?? 0} onToggleGroup={handleGroupToggle} allRows={rows} />
))}
</tbody>
</SortableContext>
@@ -389,7 +389,7 @@ export default function FallbackPage() {
onClick={() => navigate(`/models/chat/${encodeURIComponent(g.members[0].canonicalId ?? g.members[0].modelId)}`)}
className={`group/row border-b last:border-0 cursor-pointer transition-colors hover:[&>td]:bg-muted/50 [&>td:first-child]:rounded-l-lg [&>td:last-child]:rounded-r-lg ${g.members.some(m => m.enabled) ? '' : 'opacity-50'}`}
>
- <GroupHeaderCells group={g} rank={rankByKey.get(g.key) ?? 0} onToggleGroup={handleGroupToggle} />
+ <GroupHeaderCells group={g} rank={rankByKey.get(g.key) ?? 0} onToggleGroup={handleGroupToggle} allRows={rows} />
</tr>
))}
</tbody>
diff --git a/client/src/pages/ModelDetailPage.tsx b/client/src/pages/ModelDetailPage.tsx
index 412905c7..44f31393 100644
--- a/client/src/pages/ModelDetailPage.tsx
+++ b/client/src/pages/ModelDetailPage.tsx
@@ -16,7 +16,12 @@ import { ModelsTabs } from '@/components/models-tabs'
import { ModelTableHead, RowContent } from '@/components/model-table'
import {
groupQuotaBadge,
- providerLabel,
+ isMemberSplit,
+ memberEndpointTitle,
+ memberOverrideKey,
+ memberProviderLabel,
+ providerPinId,
+ splitsWithoutMember,
type FallbackEntry,
type RoutingData,
type Row,
@@ -116,25 +121,26 @@ export default function ModelDetailPage() {
})
const splits = unify?.overrides.splits ?? []
- const memberKey = (m: Row) => `${m.platform}:${m.modelId}`
- // The split control for one provider row: offer "keep separate" while the
- // model is merged with siblings, and "merge back" on a copy that was split
- // out (it lives on its own page then, so the undo must live there too).
+ // New splits are written against ONE row: an unqualified "platform:modelId"
+ // matches every relay that serves the id, so splitting one relay's card used
+ // to move both (#651). Reading accepts the plain form too, so a split saved
+ // before that is still recognised — and still undoable.
function splitActionFor(m: Row, memberCount: number): SplitAction | undefined {
if (!unify) return undefined
- const isSplit = splits.some(s => s.member === memberKey(m))
- if (isSplit) {
+ // Checked before the member-count guard on purpose: a split row is usually
+ // ALONE in its group, and that is exactly the row that needs the undo.
+ if (isMemberSplit(splits, m)) {
return {
kind: 'undo',
pending: splitMutation.isPending,
- onClick: () => splitMutation.mutate(splits.filter(s => s.member !== memberKey(m))),
+ onClick: () => splitMutation.mutate(splitsWithoutMember(splits, m)),
}
}
if (memberCount < 2) return undefined
return {
kind: 'split',
pending: splitMutation.isPending,
- onClick: () => splitMutation.mutate([...splits, { member: memberKey(m) }]),
+ onClick: () => splitMutation.mutate([...splits, { member: memberOverrideKey(m) }]),
}
}
@@ -147,6 +153,11 @@ export default function ModelDetailPage() {
.filter(e => e.keyCount > 0 && (e.canonicalId ?? e.modelId) === canonicalId)
.map(e => ({ ...(scoreById.get(e.modelDbId) ?? {}), ...e }))
.sort((a, b) => (isManual ? a.priority - b.priority : (b.score ?? 0) - (a.score ?? 0)))
+ // Endpoint disambiguation keys on (platform, model_id) across EVERY configured
+ // row — a relay whose copy was renamed sits in a DIFFERENT display group, so
+ // `members` is not a complete sibling set and scoping to it would hide the
+ // endpoint exactly when two relays collide (#651).
+ const siblings: Row[] = entries as Row[]
function handleToggle(modelDbId: number, enabled: boolean) {
saveMutation.mutate(entries.map(e => ({
@@ -208,7 +219,7 @@ export default function ModelDetailPage() {
<tbody>
{members.map((m, i) => (
<tr key={m.modelDbId} className={`border-b last:border-0 ${m.enabled ? '' : 'opacity-50'}`}>
- <RowContent row={m} rank={i + 1} draggable={false} onToggle={handleToggle} />
+ <RowContent row={m} rank={i + 1} draggable={false} onToggle={handleToggle} providerName={memberProviderLabel(m, siblings)} providerTitle={memberEndpointTitle(m, siblings)} />
</tr>
))}
</tbody>
@@ -225,6 +236,8 @@ export default function ModelDetailPage() {
<ProviderSettingsRow
key={m.modelDbId}
model={m}
+ endpointLabel={memberProviderLabel(m, siblings)}
+ endpointTitle={memberEndpointTitle(m, siblings)}
saving={modelPatchMutation.isPending && modelPatchMutation.variables?.modelDbId === m.modelDbId}
deleting={modelDeleteMutation.isPending && modelDeleteMutation.variables === m.modelDbId}
onSave={(patch) => modelPatchMutation.mutate({ modelDbId: m.modelDbId, patch })}
@@ -242,10 +255,12 @@ export default function ModelDetailPage() {
<div className="space-y-1.5">
{members.map(m => (
<div key={m.modelDbId} className="flex items-center gap-2 text-xs">
- <span className="w-28 shrink-0 text-muted-foreground">{providerLabel(m)}</span>
- <code className="min-w-0 flex-1 truncate font-mono text-[11px]">{m.modelId}</code>
+ <span className="w-28 max-w-[16rem] shrink-0 basis-auto truncate text-muted-foreground sm:w-auto sm:min-w-28" title={memberEndpointTitle(m, siblings)}>
+ {memberProviderLabel(m, siblings)}
+ </span>
+ <code className="min-w-0 flex-1 truncate font-mono text-[11px]">{providerPinId(m, siblings)}</code>
<Tooltip text={t('models.copyModelName')}>
- <CopyButton text={m.modelId} label={t('models.copyModelName')} className="border-0 bg-transparent" />
+ <CopyButton text={providerPinId(m, siblings)} label={t('models.copyModelName')} className="border-0 bg-transparent" />
</Tooltip>
</div>
))}
@@ -269,6 +284,8 @@ export default function ModelDetailPage() {
function ProviderSettingsRow({
model,
+ endpointLabel,
+ endpointTitle,
saving,
deleting,
onSave,
@@ -276,6 +293,11 @@ function ProviderSettingsRow({
splitAction,
}: {
model: Row
+ // Which provider this card is for. Carries the endpoint too, but only when
+ // two custom endpoints serve the same model id (#651).
+ endpointLabel: string
+ // Hover text for that label, set only when there was a collision to resolve.
+ endpointTitle?: string
saving: boolean
deleting: boolean
onSave: (patch: ModelSettingsPatch) => void
@@ -315,7 +337,7 @@ function ProviderSettingsRow({
return (
<div className="rounded-xl border bg-background/60 p-3">
<div className="mb-3 flex flex-wrap items-center gap-2">
- <span className="text-xs font-medium">{providerLabel(model)}</span>
+ <span className="text-xs font-medium" title={endpointTitle}>{endpointLabel}</span>
<code className="min-w-0 truncate font-mono text-[11px] text-muted-foreground">{model.modelId}</code>
<span className="rounded-full bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">{sourceLabel}</span>
{model.hasOverrides && (
diff --git a/docs/install.md b/docs/install.md
index a20c553b..83e8abb1 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -149,6 +149,19 @@ instead of duplicated.
}
```
+If two custom endpoints serve the same model id, add `"endpoint"` to a `models`
+or `fallback` entry to say which one you mean — the endpoint's URL, or the short
+handle the dashboard shows next to it. Without it, an entry that matches more
+than one endpoint is rejected rather than applied to an arbitrary one:
+
+```json
+{
+ "models": [
+ { "platform": "custom", "modelId": "deepseek-v3.1", "endpoint": "https://relay-b.example.com/v1", "enabled": false }
+ ]
+}
+```
+
## Docker image & operations
FreeLLMAPI publishes a single production image that contains the Express server and the built React dashboard:
diff --git a/server/src/__tests__/db/migrate/endpoint-identity.test.ts b/server/src/__tests__/db/migrate/endpoint-identity.test.ts
new file mode 100644
index 00000000..8192b9aa
--- /dev/null
+++ b/server/src/__tests__/db/migrate/endpoint-identity.test.ts
@@ -0,0 +1,223 @@
+import Database from 'better-sqlite3';
+import { describe, expect, it } from 'vitest';
+import { runMigrations } from '../../../db/migrate/runner.js';
+import { up as runLegacyBaseline } from '../../../db/migrations/20260101_000000_legacy_baseline.js';
+import {
+ up as endpointIdentityUp,
+ down as endpointIdentityDown,
+} from '../../../db/migrations/20260729_000001_custom_model_endpoint_identity.js';
+
+// Per-endpoint model identity (#651): the migration has to change the shape of
+// a table two other tables point INTO, on databases that are already carrying
+// user data. These cases pin the two things that could quietly destroy an
+// install: row ids drifting (which would silently re-point every fallback /
+// profile / fusion reference at a different model) and the constraint change
+// leaking into catalog platforms.
+
+function addCustomKey(db: Database.Database, baseUrl: string, label: string): number {
+ const r = db.prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)
+ VALUES ('custom', ?, 'enc', 'iv', 'tag', 'unknown', 1, ?)
+ `).run(label, baseUrl);
+ return Number(r.lastInsertRowid);
+}
+
+function addCustomModel(db: Database.Database, modelId: string, keyId: number): number {
+ const r = db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, key_id)
+ VALUES ('custom', ?, ?, 50, 50, 1, ?)
+ `).run(modelId, modelId, keyId);
+ return Number(r.lastInsertRowid);
+}
+
+/** A DB seeded the way an existing install looks: custom models + chain refs. */
+async function seededLegacyDb(): Promise<Database.Database> {
+ const db = new Database(':memory:');
+ runLegacyBaseline(db);
+ db.pragma('foreign_keys = ON');
+
+ const keyA = addCustomKey(db, 'https://relay-a.example.com/v1', 'Relay A');
+ const modelA = addCustomModel(db, 'deepseek-v3.1', keyA);
+ const legacy = db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled)
+ VALUES ('custom', 'orphan-model', 'Orphan', 50, 50, 1)
+ `).run();
+
+ db.prepare('INSERT INTO fallback_config (model_db_id, priority, enabled) VALUES (?, 900, 1)').run(modelA);
+ db.prepare('INSERT INTO fallback_config (model_db_id, priority, enabled) VALUES (?, 901, 1)')
+ .run(Number(legacy.lastInsertRowid));
+
+ const profile = db.prepare("INSERT INTO profiles (name) VALUES ('Seeded')").run();
+ db.prepare('INSERT INTO profile_models (profile_id, model_db_id, priority, enabled) VALUES (?, ?, 1, 1)')
+ .run(Number(profile.lastInsertRowid), modelA);
+
+ return db;
+}
+
+describe('custom model endpoint identity migration', () => {
+ it('keeps row ids and chain references intact on an existing DB', async () => {
+ const db = await seededLegacyDb();
+ try {
+ const customBefore = db.prepare(
+ "SELECT id, platform, model_id, key_id FROM models WHERE platform = 'custom' ORDER BY id",
+ ).all();
+ const seededIds = (customBefore as { id: number }[]).map(r => r.id);
+ const chainOf = () => db.prepare(
+ `SELECT model_db_id, priority, enabled FROM fallback_config
+ WHERE model_db_id IN (${seededIds.join(',')}) ORDER BY model_db_id`,
+ ).all();
+ const seededProfileId = (db.prepare("SELECT id FROM profiles WHERE name = 'Seeded'")
+ .get() as { id: number }).id;
+ const seededModelId = seededIds[0];
+ const profileOf = () => db.prepare(
+ 'SELECT profile_id, model_db_id, priority, enabled FROM profile_models WHERE profile_id = ? AND model_db_id = ?',
+ ).all(seededProfileId, seededModelId);
+ const fallbackBefore = chainOf();
+ const profileBefore = profileOf();
+ const totalBefore = (db.prepare('SELECT COUNT(*) AS n FROM models').get() as { n: number }).n;
+
+ await runMigrations(db, 'up');
+
+ // Ids are the load-bearing part: fallback_config / profile_models / saved
+ // fusion configs all address models BY id, so a rebuild that renumbered
+ // would silently re-point them at unrelated models.
+ expect(db.prepare(
+ "SELECT id, platform, model_id, key_id FROM models WHERE platform = 'custom' ORDER BY id",
+ ).all()).toEqual(customBefore);
+ expect(chainOf()).toEqual(fallbackBefore);
+ expect(profileOf()).toEqual(profileBefore);
+ expect(db.pragma('foreign_key_check')).toEqual([]);
+ // Nothing was dropped on the way through (later migrations only add rows).
+ expect((db.prepare('SELECT COUNT(*) AS n FROM models').get() as { n: number }).n)
+ .toBeGreaterThanOrEqual(totalBefore);
+ } finally {
+ db.close();
+ }
+ });
+
+ it('backfills the endpoint scope from each custom model\'s bound key', async () => {
+ const db = await seededLegacyDb();
+ try {
+ await runMigrations(db, 'up');
+
+ const scopes = db.prepare('SELECT model_id, endpoint_scope FROM models ORDER BY model_id')
+ .all() as { model_id: string; endpoint_scope: string }[];
+ const byId = new Map(scopes.map(s => [s.model_id, s.endpoint_scope]));
+
+ expect(byId.get('deepseek-v3.1')).toBe('https://relay-a.example.com/v1');
+ // No bound key → no scope, so a legacy row keeps the identity it had.
+ expect(byId.get('orphan-model')).toBe('');
+ // Catalog rows are never endpoint-scoped.
+ const catalogScoped = db.prepare(
+ "SELECT COUNT(*) AS n FROM models WHERE platform != 'custom' AND endpoint_scope <> ''",
+ ).get() as { n: number };
+ expect(catalogScoped.n).toBe(0);
+ } finally {
+ db.close();
+ }
+ });
+
+ it('lets two endpoints hold the same model id, but still rejects catalog duplicates', async () => {
+ const db = await seededLegacyDb();
+ try {
+ await runMigrations(db, 'up');
+
+ const keyB = addCustomKey(db, 'https://relay-b.example.com/v1', 'Relay B');
+ db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, key_id, source, endpoint_scope)
+ VALUES ('custom', 'deepseek-v3.1', 'deepseek-v3.1', 50, 50, 1, ?, 'user', 'https://relay-b.example.com/v1')
+ `).run(keyB);
+
+ const rows = db.prepare("SELECT endpoint_scope FROM models WHERE model_id = 'deepseek-v3.1' ORDER BY id")
+ .all() as { endpoint_scope: string }[];
+ expect(rows.map(r => r.endpoint_scope)).toEqual([
+ 'https://relay-a.example.com/v1',
+ 'https://relay-b.example.com/v1',
+ ]);
+
+ // Same endpoint, same model id → still one row.
+ expect(() => db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, source, endpoint_scope)
+ VALUES ('custom', 'deepseek-v3.1', 'dupe', 50, 50, 1, 'user', 'https://relay-b.example.com/v1')
+ `).run()).toThrow(/UNIQUE/i);
+
+ // Catalog platforms keep exactly the old (platform, model_id) rule.
+ const anyCatalog = db.prepare("SELECT platform, model_id FROM models WHERE platform != 'custom' LIMIT 1")
+ .get() as { platform: string; model_id: string };
+ expect(() => db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled)
+ VALUES (?, ?, 'dupe', 50, 50, 1)
+ `).run(anyCatalog.platform, anyCatalog.model_id)).toThrow(/UNIQUE/i);
+ } finally {
+ db.close();
+ }
+ });
+
+ it('keeps the AUTOINCREMENT high-water mark so deleted ids are never reused', async () => {
+ const db = await seededLegacyDb();
+ try {
+ await runMigrations(db, 'up');
+
+ // Catalog sync prunes models routinely, so the highest ids are often gone
+ // while the counter still remembers them. A rebuild that lets the counter
+ // fall back to MAX(id) would re-issue those ids, and a stale
+ // fallback_config / profile_models row would silently adopt a new model.
+ const top = (db.prepare('SELECT MAX(id) AS m FROM models').get() as { m: number }).m;
+ db.prepare('DELETE FROM profile_models WHERE model_db_id > ?').run(top - 3);
+ db.prepare('DELETE FROM fallback_config WHERE model_db_id > ?').run(top - 3);
+ db.prepare('DELETE FROM models WHERE id > ?').run(top - 3);
+ const seqBefore = (db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'models'")
+ .get() as { seq: number }).seq;
+ expect(seqBefore).toBeGreaterThan(
+ (db.prepare('SELECT MAX(id) AS m FROM models').get() as { m: number }).m,
+ );
+
+ // Exercise the rebuild itself, with no other migration able to nudge the
+ // counter back up.
+ endpointIdentityDown(db);
+ endpointIdentityUp(db);
+
+ expect((db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'models'")
+ .get() as { seq: number }).seq).toBe(seqBefore);
+ const inserted = db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled)
+ VALUES ('custom', 'fresh-model', 'Fresh', 50, 50, 1) RETURNING id
+ `).get() as { id: number };
+ expect(inserted.id).toBeGreaterThan(seqBefore - 1);
+ expect(inserted.id).toBeGreaterThan(top);
+ } finally {
+ db.close();
+ }
+ });
+
+ it('is idempotent across a down/up round trip and refuses to drop duplicates', async () => {
+ const db = await seededLegacyDb();
+ try {
+ await runMigrations(db, 'up');
+ const afterFirstUp = db.prepare('SELECT * FROM models ORDER BY id').all();
+ const schemaAfterFirstUp = db.prepare(
+ "SELECT sql FROM sqlite_master WHERE name = 'models'",
+ ).get() as { sql: string };
+
+ endpointIdentityDown(db);
+ expect(db.prepare('PRAGMA table_info(models)').all()
+ .some((c: any) => c.name === 'endpoint_scope')).toBe(false);
+
+ endpointIdentityUp(db);
+ expect(db.prepare('SELECT * FROM models ORDER BY id').all()).toEqual(afterFirstUp);
+ expect((db.prepare("SELECT sql FROM sqlite_master WHERE name = 'models'").get() as { sql: string }).sql)
+ .toBe(schemaAfterFirstUp.sql);
+ expect(db.pragma('foreign_key_check')).toEqual([]);
+
+ // With a real duplicate on the books, down() has no honest answer.
+ const keyB = addCustomKey(db, 'https://relay-b.example.com/v1', 'Relay B');
+ db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, key_id, source, endpoint_scope)
+ VALUES ('custom', 'deepseek-v3.1', 'deepseek-v3.1', 50, 50, 1, ?, 'user', 'https://relay-b.example.com/v1')
+ `).run(keyB);
+ expect(() => endpointIdentityDown(db)).toThrow(/more than one endpoint/);
+ } finally {
+ db.close();
+ }
+ });
+});
diff --git a/server/src/__tests__/db/migrate/roundtrip.test.ts b/server/src/__tests__/db/migrate/roundtrip.test.ts
index 085cd9dc..fd488b1d 100644
--- a/server/src/__tests__/db/migrate/roundtrip.test.ts
+++ b/server/src/__tests__/db/migrate/roundtrip.test.ts
@@ -21,6 +21,7 @@ const REQUEST_SERVED_MODEL_FILENAME = '20260726_000005_request_served_model.ts';
const ATTEMPT_ERROR_SUMMARY_FILENAME = '20260726_000006_attempt_error_summary.ts';
const AGENT_COMPATIBILITY_FILENAME = '20260727_000001_agent_compatibility.ts';
const TOMBSTONE_PROVENANCE_FILENAME = '20260728_000001_tombstone_provenance.ts';
+const CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME = '20260729_000001_custom_model_endpoint_identity.ts';
interface SchemaRow {
type: string;
@@ -88,6 +89,7 @@ describe('migration round trip', () => {
ATTEMPT_ERROR_SUMMARY_FILENAME,
AGENT_COMPATIBILITY_FILENAME,
TOMBSTONE_PROVENANCE_FILENAME,
+ CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME,
]);
} finally {
db.close();
diff --git a/server/src/__tests__/lib/endpoint-scope.test.ts b/server/src/__tests__/lib/endpoint-scope.test.ts
new file mode 100644
index 00000000..094e70cc
--- /dev/null
+++ b/server/src/__tests__/lib/endpoint-scope.test.ts
@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import {
+ endpointHandle,
+ endpointRefMatches,
+ endpointScopeForBaseUrl,
+ modelStatsKey,
+ normalizeBaseUrl,
+ qualifiedModelMemberId,
+} from '../../lib/endpoint-scope.js';
+
+describe('endpoint scope (#651)', () => {
+ it('normalizes a base_url the way registration stores it', () => {
+ expect(normalizeBaseUrl(' https://relay.example.com/v1/ ')).toBe('https://relay.example.com/v1');
+ expect(endpointScopeForBaseUrl(null)).toBe('');
+ expect(endpointScopeForBaseUrl('')).toBe('');
+ });
+
+ it('derives a stable, typable handle from the endpoint alone', () => {
+ expect(endpointHandle('https://relay-a.example.com/v1')).toBe('relay-a.example.com-v1');
+ expect(endpointHandle('http://127.0.0.1:11434/v1')).toBe('127.0.0.1-11434-v1');
+ // Idempotent, which is what lets a handle and the raw URL both resolve.
+ expect(endpointHandle(endpointHandle('https://relay-a.example.com/v1')))
+ .toBe(endpointHandle('https://relay-a.example.com/v1'));
+ // Different endpoints never collapse onto one handle.
+ expect(endpointHandle('https://relay-a.example.com/v1'))
+ .not.toBe(endpointHandle('https://relay-b.example.com/v1'));
+ });
+
+ it('leaves catalog stat keys exactly as they were', () => {
+ expect(modelStatsKey('groq', 'llama-3.3-70b', '')).toBe('groq:llama-3.3-70b');
+ expect(modelStatsKey('groq', 'llama-3.3-70b', null)).toBe('groq:llama-3.3-70b');
+ // Un-scoped legacy custom rows keep their old bucket too.
+ expect(modelStatsKey('custom', 'relay-model', '')).toBe('custom:relay-model');
+ expect(modelStatsKey('custom', 'relay-model', 'https://a/v1'))
+ .toBe('custom:relay-model@https://a/v1');
+ });
+
+ it('only qualifies model ids that need it', () => {
+ expect(qualifiedModelMemberId('groq', 'llama-3.3-70b', '')).toBeNull();
+ expect(qualifiedModelMemberId('custom', 'relay-model', '')).toBeNull();
+ expect(qualifiedModelMemberId('custom', 'deepseek-v3.1', 'https://relay-a.example.com/v1'))
+ .toBe('custom:deepseek-v3.1#relay-a.example.com-v1');
+ });
+
+ it('matches an endpoint reference written either way', () => {
+ const scope = 'https://relay-a.example.com/v1';
+ expect(endpointRefMatches('relay-a.example.com-v1', scope)).toBe(true);
+ expect(endpointRefMatches(scope, scope)).toBe(true);
+ expect(endpointRefMatches('relay-a.example.com/v1', scope)).toBe(true);
+ expect(endpointRefMatches('https://relay-b.example.com/v1', scope)).toBe(false);
+ expect(endpointRefMatches('', scope)).toBe(false);
+ expect(endpointRefMatches('anything', '')).toBe(false);
+ });
+});
diff --git a/server/src/__tests__/routes/custom-endpoint-identity.test.ts b/server/src/__tests__/routes/custom-endpoint-identity.test.ts
new file mode 100644
index 00000000..441b5dc2
--- /dev/null
+++ b/server/src/__tests__/routes/custom-endpoint-identity.test.ts
@@ -0,0 +1,392 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb } from '../../db/index.js';
+import { routePinnedModel, routeRequest, resolveModelGroupCandidates, refreshStatsCache, getRoutingScores, writeObservedSpeedRanks, resetSpeedRankWriteback } from '../../services/router.js';
+import { setCooldown, isOnCooldown, clearCooldownsForKey } from '../../services/ratelimit.js';
+import { getModelGroups, resolveRequestedIdToMembers, setUnifyOverrides } from '../../services/model-groups.js';
+import { noteModelRetirementSignal, resetModelRetirementObservations } from '../../services/model-retirement.js';
+import { endpointHandle, qualifiedModelMemberId } from '../../lib/endpoint-scope.js';
+import { buildModelListing } from '../../services/model-listing.js';
+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';
+
+// Per-endpoint model identity (#651). Two relays that both offer
+// `deepseek-v3.1` used to collapse into ONE models row: one enabled flag, one
+// reliability/speed bucket. Relay A going bad took relay B's copy down with it
+// (#619). These cases pin that the two copies are now genuinely separate — and,
+// just as important, that an install with a SINGLE relay behaves exactly as
+// before.
+
+const RELAY_A = 'http://127.0.0.1:18091/v1';
+const RELAY_B = 'http://127.0.0.1:18092/v1';
+const SHARED_MODEL = 'deepseek-v3.1';
+
+let dashToken = '';
+
+async function request(app: Express, method: string, path: string, body?: unknown) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const res = await fetch(`http://127.0.0.1:${addr.port}${path}`, {
+ method,
+ headers: {
+ 'Content-Type': 'application/json',
+ ...(isGatedApiPath(path) ? { Authorization: `Bearer ${dashToken}` } : {}),
+ },
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+ });
+ const data = await res.json().catch(() => null);
+ server.close();
+ return { status: res.status, body: data };
+}
+
+const post = (app: Express, path: string, body: unknown) => request(app, 'POST', path, body);
+const get = (app: Express, path: string) => request(app, 'GET', path);
+const patch = (app: Express, path: string, body: unknown) => request(app, 'PATCH', path, body);
+
+interface Row { id: number; key_id: number | null; enabled: number; endpoint_scope: string; speed_rank: number }
+
+function rowsFor(modelId: string): Row[] {
+ return getDb().prepare(
+ "SELECT id, key_id, enabled, endpoint_scope, speed_rank FROM models WHERE platform = 'custom' AND model_id = ? ORDER BY id",
+ ).all(modelId) as Row[];
+}
+
+function rowOn(scope: string, modelId = SHARED_MODEL): Row {
+ const row = rowsFor(modelId).find(r => r.endpoint_scope === scope);
+ if (!row) throw new Error(`no ${modelId} row on ${scope}`);
+ return row;
+}
+
+/** Log `n` requests against one model + key, so the stats cache has something to see. */
+function logRequests(modelId: string, keyId: number, status: 'success' | 'error', n: number, latencyMs = 500) {
+ const db = getDb();
+ const stmt = db.prepare(`
+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, request_type)
+ VALUES ('custom', ?, ?, ?, 100, 100, ?, ?, 'chat')
+ `);
+ for (let i = 0; i < n; i++) {
+ stmt.run(modelId, keyId, status, latencyMs, status === 'error' ? 'upstream timeout' : null);
+ }
+}
+
+async function registerBothRelays(app: Express) {
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_A, model: SHARED_MODEL, apiKey: 'key-a', label: 'Relay A',
+ });
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_B, model: SHARED_MODEL, apiKey: 'key-b', label: 'Relay B',
+ });
+}
+
+describe('per-endpoint identity for custom relay models (#651)', () => {
+ let app: Express;
+
+ beforeEach(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ getDb().prepare("DELETE FROM settings WHERE key = 'active_profile_id'").run();
+ resetModelRetirementObservations();
+ resetSpeedRankWriteback();
+ app = createApp();
+ dashToken = mintDashboardToken();
+ });
+
+ describe('separate rows', () => {
+ it('gives each endpoint its own row for the same model id', async () => {
+ await registerBothRelays(app);
+
+ const rows = rowsFor(SHARED_MODEL);
+ expect(rows).toHaveLength(2);
+ expect(rows.map(r => r.endpoint_scope)).toEqual([RELAY_A, RELAY_B]);
+ // Each binds to its OWN endpoint's credential, not the last one added.
+ expect(new Set(rows.map(r => r.key_id)).size).toBe(2);
+ });
+
+ it('re-registering on one endpoint updates that row only', async () => {
+ await registerBothRelays(app);
+ const before = rowsFor(SHARED_MODEL);
+
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_A, models: [{ model: SHARED_MODEL, displayName: 'DeepSeek via A' }],
+ });
+
+ const after = rowsFor(SHARED_MODEL);
+ expect(after.map(r => r.id)).toEqual(before.map(r => r.id));
+ const names = getDb().prepare(
+ "SELECT endpoint_scope, display_name FROM models WHERE platform = 'custom' AND model_id = ? ORDER BY id",
+ ).all(SHARED_MODEL) as { endpoint_scope: string; display_name: string }[];
+ expect(names).toEqual([
+ { endpoint_scope: RELAY_A, display_name: 'DeepSeek via A' },
+ { endpoint_scope: RELAY_B, display_name: SHARED_MODEL },
+ ]);
+ });
+
+ it('disables one endpoint\'s copy without touching the other', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ expect((await patch(app, `/api/models/${a.id}`, { enabled: false })).status).toBe(200);
+
+ expect(rowsFor(SHARED_MODEL).find(r => r.id === a.id)!.enabled).toBe(0);
+ expect(rowsFor(SHARED_MODEL).find(r => r.id === b.id)!.enabled).toBe(1);
+ // The still-good relay keeps serving.
+ const route = routePinnedModel(b.id);
+ expect(route).not.toBeNull();
+ expect(route!.apiKey).toBe('key-b');
+ route!.release?.();
+ expect(routePinnedModel(a.id)).toBeNull();
+ });
+
+ it('deleting one endpoint\'s copy leaves the other registered', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+
+ expect((await request(app, 'DELETE', `/api/models/custom/${a.id}`)).status).toBe(200);
+
+ const rows = rowsFor(SHARED_MODEL);
+ expect(rows).toHaveLength(1);
+ expect(rows[0]!.endpoint_scope).toBe(RELAY_B);
+ });
+ });
+
+ describe('independent stats and cooldowns', () => {
+ it('does not let one relay\'s failures drag down the other\'s score', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ logRequests(SHARED_MODEL, a.key_id!, 'error', 40);
+ logRequests(SHARED_MODEL, b.key_id!, 'success', 40);
+ refreshStatsCache(getDb(), true);
+
+ const scores = getRoutingScores().scores;
+ const scoreA = scores.find(s => s.modelDbId === a.id)!;
+ const scoreB = scores.find(s => s.modelDbId === b.id)!;
+
+ expect(scoreA.reliability).toBeLessThan(0.2);
+ expect(scoreB.reliability).toBeGreaterThan(0.8);
+ expect(scoreB.score).toBeGreaterThan(scoreA.score);
+ });
+
+ it('writes an observed speed rank per endpoint rather than one shared number', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ // Relay A answers slowly, relay B quickly — same model id, same tokens.
+ logRequests(SHARED_MODEL, a.key_id!, 'success', 40, 20_000);
+ logRequests(SHARED_MODEL, b.key_id!, 'success', 40, 200);
+ refreshStatsCache(getDb(), true);
+ writeObservedSpeedRanks(getDb());
+
+ const slow = rowsFor(SHARED_MODEL).find(r => r.id === a.id)!.speed_rank;
+ const fast = rowsFor(SHARED_MODEL).find(r => r.id === b.id)!.speed_rank;
+ expect(fast).toBeLessThan(slow);
+ });
+
+ it('keeps cooldowns per endpoint', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ setCooldown('custom', SHARED_MODEL, a.key_id!, 60_000);
+
+ expect(isOnCooldown('custom', SHARED_MODEL, a.key_id!)).toBe(true);
+ expect(isOnCooldown('custom', SHARED_MODEL, b.key_id!)).toBe(false);
+ expect(routePinnedModel(a.id)).toBeNull();
+ const route = routePinnedModel(b.id);
+ expect(route).not.toBeNull();
+ route!.release?.();
+
+ // The cooldown map is process-local and outlives the in-memory DB, so
+ // hand it back before the next case reuses these key ids.
+ clearCooldownsForKey(a.key_id!);
+ });
+
+ it('counts an end-of-life signal against one endpoint only', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+ const eol = Object.assign(new Error('HTTP 404: model no longer available'), { status: 404 });
+
+ // The route each relay hands to the failure path carries ITS endpoint, so
+ // the retirement heuristic counts corroboration per relay instead of
+ // pooling two unrelated relays' 404s into one verdict.
+ const routeA = routePinnedModel(a.id)!;
+ const routeB = routePinnedModel(b.id)!;
+ expect(routeA.endpointScope).toBe(RELAY_A);
+ expect(routeB.endpointScope).toBe(RELAY_B);
+ routeA.release?.();
+ routeB.release?.();
+
+ // Two 'probable' signals are needed to act; feeding one to each endpoint
+ // must not add up to a verdict against either. (User-added models are
+ // never auto-retired anyway — that guard is asserted in
+ // services/model-retirement.test.ts — so both stay on.)
+ noteModelRetirementSignal(
+ { modelDbId: a.id, platform: 'custom', modelId: SHARED_MODEL, endpointScope: routeA.endpointScope }, eol, {},
+ );
+ noteModelRetirementSignal(
+ { modelDbId: b.id, platform: 'custom', modelId: SHARED_MODEL, endpointScope: routeB.endpointScope }, eol, {},
+ );
+
+ expect(rowsFor(SHARED_MODEL).map(r => r.enabled)).toEqual([1, 1]);
+ });
+ });
+
+ describe('naming', () => {
+ it('routes an endpoint-qualified id to that endpoint\'s row', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+ const groups = getModelGroups();
+
+ expect(resolveRequestedIdToMembers(`custom:${SHARED_MODEL}#${endpointHandle(RELAY_A)}`, groups))
+ .toEqual([a.id]);
+ expect(resolveRequestedIdToMembers(`custom:${SHARED_MODEL}#${endpointHandle(RELAY_B)}`, groups))
+ .toEqual([b.id]);
+ // The endpoint URL itself works too, for anyone pasting what they typed
+ // into the dashboard.
+ expect(resolveRequestedIdToMembers(`custom:${SHARED_MODEL}#${RELAY_B}`, groups)).toEqual([b.id]);
+ // An endpoint that doesn't serve it is not a match.
+ expect(resolveRequestedIdToMembers(`custom:${SHARED_MODEL}#nope.example.com`, groups)).toBeNull();
+ });
+
+ it('keeps a bare model id reaching BOTH relays after one is renamed', async () => {
+ // Display name is presentation, not identity. Renaming relay A's copy
+ // moves it into a different display-name group — that must not make it
+ // (or its sibling) unreachable by the bare id every client already uses.
+ await registerBothRelays(app);
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_A, models: [{ model: SHARED_MODEL, displayName: 'DeepSeek via A' }],
+ });
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ const groups = getModelGroups();
+ // Precondition: the rename really did split them across groups.
+ expect(new Set(groups.filter(g => g.members.some(m => m.model_id === SHARED_MODEL))
+ .map(g => g.groupKey)).size).toBe(2);
+
+ expect(resolveRequestedIdToMembers(SHARED_MODEL, groups)?.sort())
+ .toEqual([a.id, b.id].sort());
+ // And the platform-qualified form still reaches both too.
+ expect(resolveRequestedIdToMembers(`custom:${SHARED_MODEL}`, groups)?.sort())
+ .toEqual([a.id, b.id].sort());
+ });
+
+ it('routes a bare id to the renamed relay when the other one is cooled down', async () => {
+ // The failover a bare id is supposed to give you, across a display-name
+ // boundary: relay B is benched, so the request has to land on relay A.
+ await registerBothRelays(app);
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_A, models: [{ model: SHARED_MODEL, displayName: 'DeepSeek via A' }],
+ });
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ setCooldown('custom', SHARED_MODEL, b.key_id!, 60_000);
+ try {
+ const ids = resolveRequestedIdToMembers(SHARED_MODEL, getModelGroups())!;
+ const route = routeRequest(1000, undefined, undefined, false, false, undefined,
+ resolveModelGroupCandidates(ids));
+ expect(route.modelDbId).toBe(a.id);
+ route.release?.();
+ } finally {
+ clearCooldownsForKey(b.key_id!);
+ }
+ });
+
+ it('splits only the named relay when a split override uses its qualified id', async () => {
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+ const qualifiedA = qualifiedModelMemberId('custom', SHARED_MODEL, RELAY_A)!;
+
+ setUnifyOverrides({ merges: [], splits: [{ member: qualifiedA }] });
+
+ const groups = getModelGroups();
+ const groupOf = (id: number) => groups.find(g => g.members.some(m => m.model_db_id === id))!;
+ expect(groupOf(a.id).groupKey).not.toBe(groupOf(b.id).groupKey);
+ expect(groupOf(a.id).members.map(m => m.model_db_id)).toEqual([a.id]);
+ expect(groupOf(b.id).members.map(m => m.model_db_id)).toEqual([b.id]);
+
+ // Splitting for display still must not shrink what the bare id reaches.
+ expect(resolveRequestedIdToMembers(SHARED_MODEL, groups)?.sort())
+ .toEqual([a.id, b.id].sort());
+ });
+
+ it('honours a split saved in the pre-#651 plain form', async () => {
+ // Upgrading must not orphan an existing override: the stored key is the
+ // unqualified member id, and nothing rewrites it on read.
+ await registerBothRelays(app);
+ const a = rowOn(RELAY_A);
+ const b = rowOn(RELAY_B);
+
+ setUnifyOverrides({ merges: [], splits: [{ member: `custom:${SHARED_MODEL}` }] });
+
+ const groups = getModelGroups();
+ // An unqualified key names BOTH relays, so they share one split group —
+ // exactly what it meant before #651, left alone rather than reinterpreted.
+ const groupOf = (id: number) => groups.find(g => g.members.some(m => m.model_db_id === id))!;
+ expect(groupOf(a.id).groupKey).toBe(groupOf(b.id).groupKey);
+ expect(groupOf(a.id).groupKey).toContain('__split__');
+ expect(groupOf(a.id).members.map(m => m.model_db_id).sort()).toEqual([a.id, b.id].sort());
+
+ // And the bare id still reaches both, so the split stays cosmetic.
+ expect(resolveRequestedIdToMembers(SHARED_MODEL, groups)?.sort())
+ .toEqual([a.id, b.id].sort());
+ });
+
+ it('keeps a bare model id working — it spans both relays', async () => {
+ await registerBothRelays(app);
+ const groups = getModelGroups();
+ const ids = resolveRequestedIdToMembers(SHARED_MODEL, groups);
+ expect(ids?.sort()).toEqual([rowOn(RELAY_A).id, rowOn(RELAY_B).id].sort());
+ });
+
+ it('advertises exactly one catalog entry for a duplicated model id', async () => {
+ await registerBothRelays(app);
+ // The public listing is still ONE logical model — clients that copied the
+ // id keep working, and the two relays are its failover set.
+ const listed = buildModelListing().models.filter(m => m.id === SHARED_MODEL);
+ expect(listed).toHaveLength(1);
+ expect(listed[0]!.platforms).toEqual(['custom']);
+ });
+
+ it('leaves a single-endpoint install completely un-qualified', async () => {
+ await post(app, '/api/keys/custom', {
+ baseUrl: RELAY_A, model: 'solo-model', apiKey: 'key-a', label: 'Relay A',
+ });
+ const groups = getModelGroups();
+ const soloId = rowsFor('solo-model')[0]!.id;
+
+ // Bare id and the plain platform:model_id form both still resolve.
+ expect(resolveRequestedIdToMembers('solo-model', groups)).toEqual([soloId]);
+ expect(resolveRequestedIdToMembers('custom:solo-model', groups)).toEqual([soloId]);
+
+ // And the dashboard is told there is nothing to disambiguate.
+ const listed = (await get(app, '/api/models')).body as any[];
+ const row = listed.find(m => m.modelId === 'solo-model');
+ expect(row.qualifiedModelId).toBe(`custom:solo-model#${endpointHandle(RELAY_A)}`);
+ const catalogRow = listed.find(m => m.platform !== 'custom');
+ expect(catalogRow.endpointScope).toBeNull();
+ expect(catalogRow.qualifiedModelId).toBeNull();
+ });
+
+ it('surfaces the endpoint on every duplicated row so the dashboard can label it', async () => {
+ await registerBothRelays(app);
+ const listed = (await get(app, '/api/fallback')).body as any[];
+ const dupes = listed.filter(m => m.modelId === SHARED_MODEL);
+
+ expect(dupes).toHaveLength(2);
+ expect(dupes.map(d => d.endpointScope).sort()).toEqual([RELAY_A, RELAY_B]);
+ expect(dupes.map(d => d.keyLabel).sort()).toEqual(['Relay A', 'Relay B']);
+ expect(dupes.map(d => d.qualifiedModelId).sort()).toEqual([
+ qualifiedModelMemberId('custom', SHARED_MODEL, RELAY_A),
+ qualifiedModelMemberId('custom', SHARED_MODEL, RELAY_B),
+ ].sort());
+ });
+ });
+});
diff --git a/server/src/__tests__/services/declarative-config.test.ts b/server/src/__tests__/services/declarative-config.test.ts
index d03c1620..998f86c8 100644
--- a/server/src/__tests__/services/declarative-config.test.ts
+++ b/server/src/__tests__/services/declarative-config.test.ts
@@ -191,3 +191,92 @@ describe('declarative config import', () => {
expect(() => applyDeclarativeConfigFromEnv()).toThrow();
});
});
+
+// Per-endpoint identity (#651): two relays can hold the same model id, so a
+// declarative `models:` or `fallback:` entry naming only (platform, modelId) is
+// ambiguous for platform 'custom'. Patching whichever row SQLite returned first
+// would silently edit the wrong relay, so the entry has to say which endpoint
+// it means.
+describe('declarative config with two relays serving one model id', () => {
+ const RELAY_A = 'http://127.0.0.1:9301/v1';
+ const RELAY_B = 'http://127.0.0.1:9302/v1';
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ });
+
+ beforeEach(() => {
+ delete process.env.FREEAPI_CONFIG_JSON;
+ delete process.env.FREEAPI_CONFIG_PATH;
+ const db = getDb();
+ db.prepare("DELETE FROM fallback_config WHERE model_db_id IN (SELECT id FROM models WHERE platform = 'custom')").run();
+ db.prepare("DELETE FROM profile_models WHERE model_db_id IN (SELECT id FROM models WHERE platform = 'custom')").run();
+ db.prepare("DELETE FROM models WHERE platform = 'custom'").run();
+ db.prepare('DELETE FROM api_keys').run();
+ applyDeclarativeConfig({
+ customProviders: [
+ { baseUrl: RELAY_A, apiKey: 'sk-a', label: 'Relay A', models: ['shared-model'] },
+ { baseUrl: RELAY_B, apiKey: 'sk-b', label: 'Relay B', models: ['shared-model'] },
+ ],
+ });
+ });
+
+ afterEach(() => restoreEnv());
+
+ function rowOn(scope: string) {
+ return getDb().prepare(
+ "SELECT id, display_name, enabled FROM models WHERE platform = 'custom' AND model_id = 'shared-model' AND endpoint_scope = ?",
+ ).get(scope) as { id: number; display_name: string; enabled: number };
+ }
+
+ it('refuses an ambiguous model edit instead of patching an arbitrary relay', () => {
+ expect(() => applyDeclarativeConfig({
+ models: [{ platform: 'custom', modelId: 'shared-model', displayName: 'Renamed' }],
+ })).toThrow(/more than one endpoint/i);
+
+ // Nothing was written — the whole apply is one transaction.
+ expect(rowOn(RELAY_A).display_name).toBe('shared-model');
+ expect(rowOn(RELAY_B).display_name).toBe('shared-model');
+ });
+
+ it('edits exactly the endpoint the entry names', () => {
+ applyDeclarativeConfig({
+ models: [{ platform: 'custom', modelId: 'shared-model', endpoint: RELAY_B, displayName: 'Only B' }],
+ });
+
+ expect(rowOn(RELAY_A).display_name).toBe('shared-model');
+ expect(rowOn(RELAY_B).display_name).toBe('Only B');
+ });
+
+ it('rejects an endpoint that serves no such model', () => {
+ expect(() => applyDeclarativeConfig({
+ models: [{ platform: 'custom', modelId: 'shared-model', endpoint: 'http://127.0.0.1:9999/v1', displayName: 'x' }],
+ })).toThrow(/no custom endpoint/i);
+ });
+
+ it('applies a fallback entry to the named endpoint only', () => {
+ const before = getDb().prepare('SELECT priority FROM fallback_config WHERE model_db_id = ?')
+ .get(rowOn(RELAY_A).id) as { priority: number };
+
+ applyDeclarativeConfig({
+ fallback: [{ platform: 'custom', modelId: 'shared-model', endpoint: RELAY_B, priority: 3 }],
+ });
+
+ expect((getDb().prepare('SELECT priority FROM fallback_config WHERE model_db_id = ?')
+ .get(rowOn(RELAY_B).id) as { priority: number }).priority).toBe(3);
+ expect((getDb().prepare('SELECT priority FROM fallback_config WHERE model_db_id = ?')
+ .get(rowOn(RELAY_A).id) as { priority: number }).priority).toBe(before.priority);
+ });
+
+ it('leaves a single-endpoint declaration working with no endpoint field', () => {
+ const db = getDb();
+ db.prepare("DELETE FROM fallback_config WHERE model_db_id = ?").run(rowOn(RELAY_B).id);
+ db.prepare("DELETE FROM profile_models WHERE model_db_id = ?").run(rowOn(RELAY_B).id);
+ db.prepare("DELETE FROM models WHERE platform = 'custom' AND endpoint_scope = ?").run(RELAY_B);
+ applyDeclarativeConfig({
+ models: [{ platform: 'custom', modelId: 'shared-model', displayName: 'Solo' }],
+ });
+ expect(rowOn(RELAY_A).display_name).toBe('Solo');
+ });
+});
diff --git a/server/src/__tests__/services/match-tier-routing.test.ts b/server/src/__tests__/services/match-tier-routing.test.ts
new file mode 100644
index 00000000..3ef492ab
--- /dev/null
+++ b/server/src/__tests__/services/match-tier-routing.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import {
+ resolveModelGroupCandidates,
+ routeRequest,
+ refreshStatsCache,
+ setRoutingStrategy,
+} from '../../services/router.js';
+import { encrypt } from '../../lib/crypto.js';
+
+// A slug-only match is a FALLBACK, not an equal candidate (#651). The router
+// re-orders whatever chain it is handed by live score, so the tier has to be
+// expressed as something orderChain honours as a TIER — otherwise a
+// coincidental slug sibling with better recent numbers silently answers a
+// request that named a different model literally.
+
+function addKey(platform: string): number {
+ const { encrypted, iv, authTag } = encrypt(`${platform}-secret`);
+ const r = getDb().prepare(`
+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)
+ VALUES (?, ?, ?, ?, ?, 'healthy', 1)
+ `).run(platform, platform, encrypted, iv, authTag);
+ return Number(r.lastInsertRowid);
+}
+
+function addModel(platform: string, modelId: string): number {
+ const r = getDb().prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, source)
+ VALUES (?, ?, ?, 50, 50, 1, 'catalog')
+ `).run(platform, modelId, modelId);
+ return Number(r.lastInsertRowid);
+}
+
+/** Give one (model, key) a spotless record so its bandit score is high. */
+function logSuccesses(platform: string, modelId: string, keyId: number, n: number) {
+ const stmt = getDb().prepare(`
+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, request_type)
+ VALUES (?, ?, ?, 'success', 100, 400, 200, 'chat')
+ `);
+ for (let i = 0; i < n; i++) stmt.run(platform, modelId, keyId);
+}
+
+function logFailures(platform: string, modelId: string, keyId: number, n: number) {
+ const stmt = getDb().prepare(`
+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, request_type)
+ VALUES (?, ?, ?, 'error', 100, 0, 30000, 'upstream timeout', 'chat')
+ `);
+ for (let i = 0; i < n; i++) stmt.run(platform, modelId, keyId);
+}
+
+describe('slug-match demotion survives the router', () => {
+ let literalId: number;
+ let slugId: number;
+
+ beforeEach(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ getDb().prepare("DELETE FROM settings WHERE key = 'active_profile_id'").run();
+ getDb().prepare('DELETE FROM api_keys').run();
+ setRoutingStrategy('balanced');
+
+ const groqKey = addKey('groq');
+ const cerebrasKey = addKey('cerebras');
+ literalId = addModel('groq', 'tier-test-model');
+ slugId = addModel('cerebras', 'tier-test-other');
+
+ // The fallback candidate is measurably BETTER than the literal one, so
+ // score alone would put it first.
+ logFailures('groq', 'tier-test-model', groqKey, 30);
+ logSuccesses('cerebras', 'tier-test-other', cerebrasKey, 40);
+ refreshStatsCache(getDb(), true);
+ });
+
+ it('orders a demoted member behind a literal one despite a better score', () => {
+ const chain = resolveModelGroupCandidates([literalId, slugId], new Set([slugId]));
+ expect(chain.map(c => c.model_db_id)).toEqual([literalId, slugId]);
+ });
+
+ it('still dispatches to the literal model when the router re-sorts the chain', () => {
+ // routeRequest runs its own orderChain over the prefetched chain, which is
+ // where a tier expressed as mere ordering would be lost.
+ const chain = resolveModelGroupCandidates([literalId, slugId], new Set([slugId]));
+ const route = routeRequest(1000, undefined, undefined, false, false, undefined, chain);
+ expect(route.modelDbId).toBe(literalId);
+ route.release?.();
+ });
+
+ it('falls through to the demoted member once the literal one is ruled out', () => {
+ const chain = resolveModelGroupCandidates([literalId, slugId], new Set([slugId]));
+ const route = routeRequest(1000, undefined, undefined, false, false, new Set([literalId]), chain);
+ expect(route.modelDbId).toBe(slugId);
+ route.release?.();
+ });
+
+ it('leaves an untiered chain ordered purely by score', () => {
+ const chain = resolveModelGroupCandidates([literalId, slugId]);
+ expect(chain.map(c => c.model_db_id)).toEqual([slugId, literalId]);
+ });
+});
diff --git a/server/src/__tests__/services/model-groups.test.ts b/server/src/__tests__/services/model-groups.test.ts
index 8e8c48e5..94bf5281 100644
--- a/server/src/__tests__/services/model-groups.test.ts
+++ b/server/src/__tests__/services/model-groups.test.ts
@@ -5,6 +5,8 @@ import {
slugifyGroupLabel,
groupRows,
resolveRequestedIdToMembers,
+ resolveRequestedIdToTieredMembers,
+ demotedMemberIds,
type GroupableRow,
type UnifyOverrides,
} from '../../services/model-groups.js';
@@ -160,3 +162,87 @@ describe('resolveRequestedIdToMembers', () => {
expect(resolveRequestedIdToMembers('does-not-exist', groups)).toBeNull();
});
});
+
+// A canonical id is a SLUG of a display name, so it can coincide with some other
+// model's literal model_id. Resolution unions both matches — grouping must never
+// shrink what an id reaches (#651) — but the two are not equally intended: an id
+// typed literally must be tried literally first, and a coincidental slug sibling
+// is only a fallback. Anything else is a silent substitution.
+describe('slug / model_id collisions resolve as an ordered union', () => {
+ // The one case that exists in the shipped catalog: the Cloudflare row's
+ // display name "Gemma 4 26B-A4B it (CF)" slugs to `gemma-4-26b-a4b-it`, which
+ // is Google's literal model_id in a different group.
+ function gemmaCatalog(): GroupableRow[] {
+ return [
+ row(121, 'cloudflare', '@cf/google/gemma-4-26b-a4b-it', 'Gemma 4 26B-A4B it (CF)', 22),
+ row(139, 'google', 'gemma-4-26b-a4b-it', 'Gemma 4 26B IT', 20),
+ ];
+ }
+
+ it('puts the literally-requested model first and the slug sibling after', () => {
+ const groups = groupRows(gemmaCatalog(), NO_OVERRIDES);
+ const cf = groups.find(g => g.members.some(m => m.model_db_id === 121))!;
+ expect(cf.canonicalId).toBe('gemma-4-26b-a4b-it');
+ expect(groups.find(g => g.members.some(m => m.model_db_id === 139))!.groupKey)
+ .not.toBe(cf.groupKey);
+
+ // Literal match (139) first; the slug-only match (121) stays reachable but
+ // can only serve once the literal one is exhausted.
+ expect(resolveRequestedIdToMembers('gemma-4-26b-a4b-it', groups)).toEqual([139, 121]);
+ });
+
+ it('reports which members were reached only through a slug', () => {
+ const groups = groupRows(gemmaCatalog(), NO_OVERRIDES);
+ const tiered = resolveRequestedIdToTieredMembers('gemma-4-26b-a4b-it', groups)!;
+ expect(tiered).toEqual([
+ { modelDbId: 139, tier: 'literal' },
+ { modelDbId: 121, tier: 'slug' },
+ ]);
+ expect([...demotedMemberIds(tiered)]).toEqual([121]);
+ });
+
+ it('still resolves the Cloudflare row by its own literal id, alone', () => {
+ const groups = groupRows(gemmaCatalog(), NO_OVERRIDES);
+ expect(resolveRequestedIdToMembers('@cf/google/gemma-4-26b-a4b-it', groups)).toEqual([121]);
+ });
+
+ it('keeps a plain slug request unaffected when nothing collides', () => {
+ const groups = groupRows(catalog(), NO_OVERRIDES);
+ // "Llama 3.3 70B" slugs to `llama-3.3-70b`, which no member carries as its
+ // literal model_id — so the whole group is reached through the slug, and
+ // with nothing above it the tier changes nothing about what serves first.
+ const g = groups.find(gr => gr.canonicalId === 'llama-3.3-70b')!;
+ const ids = resolveRequestedIdToMembers(g.canonicalId, groups)!;
+ expect([...ids].sort()).toEqual(g.members.map(m => m.model_db_id).sort());
+ expect(demotedMemberIds(resolveRequestedIdToTieredMembers(g.canonicalId, groups)!).size)
+ .toBe(g.members.length);
+ });
+
+ it('treats a slug that a member also carries literally as a literal match', () => {
+ const groups = groupRows(catalog(), NO_OVERRIDES);
+ // `gpt-oss-120b` is both this group's slug and row 1's own model_id, so
+ // nothing is demoted — the common case where the two agree.
+ const tiered = resolveRequestedIdToTieredMembers('gpt-oss-120b', groups)!;
+ expect(demotedMemberIds(tiered).size).toBe(0);
+ expect(tiered.some(t => t.modelDbId === 1)).toBe(true);
+ });
+
+ it('treats a user-merged group as a first-class match, not a fallback', () => {
+ // The user asserted this name themselves, so a slug match on it ranks with
+ // the literal ones rather than behind them.
+ const rows = gemmaCatalog();
+ const merged: UnifyOverrides = {
+ merges: [{ into: 'Gemma 4 26B-A4B it', keys: ['cloudflare:@cf/google/gemma-4-26b-a4b-it'] }],
+ splits: [],
+ };
+ const groups = groupRows(rows, merged);
+ const tiered = resolveRequestedIdToTieredMembers('gemma-4-26b-a4b-it', groups)!;
+ expect(tiered.every(t => t.tier === 'literal')).toBe(true);
+ });
+
+ it('groups the catalog in a stable order regardless of row order', () => {
+ const forward = groupRows(catalog(), NO_OVERRIDES).map(g => g.canonicalId).sort();
+ const reversed = groupRows([...catalog()].reverse(), NO_OVERRIDES).map(g => g.canonicalId).sort();
+ expect(reversed).toEqual(forward);
+ });
+});
diff --git a/server/src/__tests__/services/model-retirement.test.ts b/server/src/__tests__/services/model-retirement.test.ts
index 57eafb40..6275dd17 100644
--- a/server/src/__tests__/services/model-retirement.test.ts
+++ b/server/src/__tests__/services/model-retirement.test.ts
@@ -28,7 +28,7 @@ function seedModel(modelId = MODEL_ID): number {
db.prepare(`
INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, source)
VALUES (?, ?, 'EOL Test', 50, 50, 1, 'catalog')
- ON CONFLICT(platform, model_id) DO UPDATE SET enabled = 1
+ ON CONFLICT(platform, model_id, endpoint_scope) DO UPDATE SET enabled = 1
`).run(PLATFORM, modelId);
const row = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?')
.get(PLATFORM, modelId) as { id: number };
@@ -157,7 +157,7 @@ describe('noteModelRetirementSignal (auto-disable with a reason — #634)', () =
db.prepare(`
INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled, source)
VALUES ('custom', 'eol-test-custom', 'Custom EOL', 50, 50, 1, 'user')
- ON CONFLICT(platform, model_id) DO UPDATE SET enabled = 1
+ ON CONFLICT(platform, model_id, endpoint_scope) DO UPDATE SET enabled = 1
`).run();
const row = db.prepare("SELECT id FROM models WHERE platform = 'custom' AND model_id = 'eol-test-custom'")
.get() as { id: number };
diff --git a/server/src/__tests__/services/ratelimit.test.ts b/server/src/__tests__/services/ratelimit.test.ts
index aea3d40c..ff21bd6f 100644
--- a/server/src/__tests__/services/ratelimit.test.ts
+++ b/server/src/__tests__/services/ratelimit.test.ts
@@ -315,7 +315,7 @@ describe('Rate Limiter', () => {
'navy', ?, ?, 1, 1, 'Large', 20, NULL, NULL, ?,
?, NULL, 1, 0, 1
)
- ON CONFLICT(platform, model_id) DO UPDATE SET
+ ON CONFLICT(platform, model_id, endpoint_scope) DO UPDATE SET
tpd_limit = excluded.tpd_limit,
monthly_token_budget = excluded.monthly_token_budget
`).run(modelId, `${modelId} (NavyAI)`, tpdLimit, monthlyTokenBudget);
diff --git a/server/src/db/migrate/defaults.ts b/server/src/db/migrate/defaults.ts
index 6776f0ec..52607b6e 100644
--- a/server/src/db/migrate/defaults.ts
+++ b/server/src/db/migrate/defaults.ts
@@ -16,6 +16,7 @@ import * as requestServedModel from '../migrations/20260726_000005_request_serve
import * as attemptErrorSummary from '../migrations/20260726_000006_attempt_error_summary.js';
import * as agentCompatibility from '../migrations/20260727_000001_agent_compatibility.js';
import * as tombstoneProvenance from '../migrations/20260728_000001_tombstone_provenance.js';
+import * as customModelEndpointIdentity from '../migrations/20260729_000001_custom_model_endpoint_identity.js';
export interface MigrationModule {
up(db: Db): void;
@@ -44,6 +45,7 @@ export const REQUEST_SERVED_MODEL_FILENAME = '20260726_000005_request_served_mod
export const ATTEMPT_ERROR_SUMMARY_FILENAME = '20260726_000006_attempt_error_summary.ts';
export const AGENT_COMPATIBILITY_FILENAME = '20260727_000001_agent_compatibility.ts';
export const TOMBSTONE_PROVENANCE_FILENAME = '20260728_000001_tombstone_provenance.ts';
+export const CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME = '20260729_000001_custom_model_endpoint_identity.ts';
export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [
{ filename: LEGACY_BASELINE_FILENAME, module: legacyBaseline },
@@ -63,4 +65,5 @@ export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [
{ filename: ATTEMPT_ERROR_SUMMARY_FILENAME, module: attemptErrorSummary },
{ filename: AGENT_COMPATIBILITY_FILENAME, module: agentCompatibility },
{ filename: TOMBSTONE_PROVENANCE_FILENAME, module: tombstoneProvenance },
+ { filename: CUSTOM_MODEL_ENDPOINT_IDENTITY_FILENAME, module: customModelEndpointIdentity },
];
diff --git a/server/src/db/migrations/20260729_000001_custom_model_endpoint_identity.ts b/server/src/db/migrations/20260729_000001_custom_model_endpoint_identity.ts
new file mode 100644
index 00000000..d9e75b3f
--- /dev/null
+++ b/server/src/db/migrations/20260729_000001_custom_model_endpoint_identity.ts
@@ -0,0 +1,165 @@
+// Migration: per-endpoint identity for custom relay models (#651)
+// Created: 2026-07-29
+//
+// DOWN: reversible (throws when duplicates exist — see below)
+//
+// `models` was unique on (platform, model_id). Every custom relay is stored
+// under platform = 'custom', so two relays offering the same model id could not
+// coexist: the second registration silently rebound the first one's row. One
+// enabled flag, one set of ranks, one stats bucket — turning the model off
+// because relay A was broken turned it off for relay B as well (#619).
+//
+// This adds `endpoint_scope` (the endpoint's normalized base_url, '' for every
+// catalog platform) and moves uniqueness to (platform, model_id,
+// endpoint_scope). Catalog rows all share the '' scope, so their constraint is
+// bit-for-bit the old one; only custom rows gain room for a sibling.
+//
+// SQLite cannot drop a table-level UNIQUE, so `models` is rebuilt. Two details
+// make that safe on a live DB:
+// - row ids are copied verbatim, so fallback_config / profile_models /
+// saved fusion configs keep pointing at the same models;
+// - `PRAGMA foreign_keys` is a no-op inside a transaction and the migration
+// runner wraps up() in one, so the child rows are parked in temp tables
+// across the DROP and restored after the rename. Renaming `models` itself
+// is avoided on purpose: with foreign keys on, a rename rewrites the
+// REFERENCES clauses of every child table to the new name.
+//
+// Schema only — no catalog data.
+
+import type { Db } from '../types.js';
+
+// The models table as of this migration, plus the new column. Written out in
+// full rather than derived, so the rebuilt schema is auditable here and
+// identical on every run.
+const MODELS_COLUMNS = `
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ platform TEXT NOT NULL,
+ model_id TEXT NOT NULL,
+ display_name TEXT NOT NULL,
+ intelligence_rank INTEGER NOT NULL,
+ speed_rank INTEGER NOT NULL,
+ size_label TEXT NOT NULL DEFAULT '',
+ rpm_limit INTEGER,
+ rpd_limit INTEGER,
+ tpm_limit INTEGER,
+ tpd_limit INTEGER,
+ monthly_token_budget TEXT NOT NULL DEFAULT '',
+ context_window INTEGER,
+ enabled INTEGER NOT NULL DEFAULT 1,
+ supports_vision INTEGER NOT NULL DEFAULT 0,
+ key_id INTEGER,
+ supports_tools INTEGER NOT NULL DEFAULT 0,
+ paid_input_per_m REAL,
+ paid_output_per_m REAL,
+ source TEXT NOT NULL DEFAULT 'catalog'`;
+
+const CARRIED_COLUMNS = [
+ 'id', 'platform', 'model_id', 'display_name', 'intelligence_rank', 'speed_rank',
+ 'size_label', 'rpm_limit', 'rpd_limit', 'tpm_limit', 'tpd_limit',
+ 'monthly_token_budget', 'context_window', 'enabled', 'supports_vision', 'key_id',
+ 'supports_tools', 'paid_input_per_m', 'paid_output_per_m', 'source',
+].join(', ');
+
+// Tables whose rows must survive the DROP. Discovered from the schema rather
+// than hard-coded, so a table added later that references models is carried too.
+function childTablesOfModels(db: Db): string[] {
+ const tables = db.prepare(`
+ SELECT name FROM sqlite_master
+ WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> 'models'
+ ORDER BY name
+ `).all() as { name: string }[];
+ return tables
+ .filter(t => (db.prepare(`PRAGMA foreign_key_list("${t.name}")`).all() as { table: string }[])
+ .some(fk => fk.table === 'models'))
+ .map(t => t.name);
+}
+
+function rebuildModels(db: Db, extraColumns: string, copiedColumns: string, unique: string): void {
+ const children = childTablesOfModels(db);
+ // AUTOINCREMENT's high-water mark. DROP TABLE takes the sqlite_sequence row
+ // with it, and copying rows back only pushes the counter to the highest id
+ // PRESENT — so a table whose top rows were deleted (catalog sync prunes
+ // models routinely) would start handing out ids it has already used. Stale
+ // fallback_config / profile_models rows pointing at a deleted model would
+ // then silently adopt an unrelated new one.
+ const seqRow = db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'models'")
+ .get() as { seq: number } | undefined;
+ for (const child of children) {
+ db.exec(`CREATE TEMP TABLE "_endpoint_identity_${child}" AS SELECT * FROM "${child}"`);
+ db.exec(`DELETE FROM "${child}"`);
+ }
+
+ db.exec(`
+ CREATE TABLE models_endpoint_identity (${MODELS_COLUMNS}${extraColumns},
+ ${unique}
+ );
+ INSERT INTO models_endpoint_identity (${copiedColumns})
+ SELECT ${copiedColumns} FROM models;
+ DROP TABLE models;
+ ALTER TABLE models_endpoint_identity RENAME TO models;
+ `);
+
+ if (seqRow) {
+ // sqlite_sequence has no unique index, so no upsert: update the row the
+ // rename carried over, or re-create it if the table was empty.
+ const restored = db.prepare("UPDATE sqlite_sequence SET seq = ? WHERE name = 'models' AND seq < ?")
+ .run(seqRow.seq, seqRow.seq);
+ if (restored.changes === 0
+ && !db.prepare("SELECT 1 FROM sqlite_sequence WHERE name = 'models'").get()) {
+ db.prepare("INSERT INTO sqlite_sequence (name, seq) VALUES ('models', ?)").run(seqRow.seq);
+ }
+ }
+
+ for (const child of children) {
+ db.exec(`INSERT INTO "${child}" SELECT * FROM "_endpoint_identity_${child}"`);
+ db.exec(`DROP TABLE "_endpoint_identity_${child}"`);
+ }
+}
+
+export function up(db: Db): void {
+ rebuildModels(
+ db,
+ `,\n endpoint_scope TEXT NOT NULL DEFAULT ''`,
+ CARRIED_COLUMNS,
+ 'UNIQUE(platform, model_id, endpoint_scope)',
+ );
+
+ // Backfill: a custom row's scope is the base_url of the key it is bound to.
+ // Rows whose key is gone (or that predate per-endpoint binding) keep '' —
+ // exactly the identity they have today, so nothing about them changes.
+ const bound = db.prepare(`
+ SELECT m.id AS id, k.base_url AS base_url
+ FROM models m
+ JOIN api_keys k ON k.id = m.key_id AND k.platform = 'custom'
+ WHERE m.platform = 'custom' AND k.base_url IS NOT NULL AND k.base_url <> ''
+ `).all() as { id: number; base_url: string }[];
+ const setScope = db.prepare('UPDATE models SET endpoint_scope = ? WHERE id = ?');
+ for (const row of bound) {
+ setScope.run(row.base_url.trim().replace(/\/+$/, ''), row.id);
+ }
+
+ db.exec(`
+ CREATE INDEX IF NOT EXISTS idx_models_endpoint_scope
+ ON models(endpoint_scope) WHERE endpoint_scope <> '';
+ `);
+}
+
+export function down(db: Db): void {
+ // Going back means two relays' copies of one model id would have to share a
+ // row again, and there is no honest way to pick which endpoint's settings
+ // survive. Refuse rather than silently discard one.
+ const collisions = db.prepare(`
+ SELECT platform, model_id, COUNT(*) AS n
+ FROM models GROUP BY platform, model_id HAVING COUNT(*) > 1
+ `).all() as { platform: string; model_id: string; n: number }[];
+ if (collisions.length > 0) {
+ const sample = collisions.slice(0, 3).map(c => `${c.platform}/${c.model_id} (${c.n})`).join(', ');
+ throw new Error(
+ `Cannot revert per-endpoint model identity: ${collisions.length} model id(s) exist on more than one endpoint — ${sample}. ` +
+ 'Delete the duplicate rows (or the extra endpoint) first.',
+ );
+ }
+
+ db.exec('DROP INDEX IF EXISTS idx_models_endpoint_scope;');
+ rebuildModels(db, '', CARRIED_COLUMNS, 'UNIQUE(platform, model_id)');
+}
diff --git a/server/src/lib/endpoint-scope.ts b/server/src/lib/endpoint-scope.ts
new file mode 100644
index 00000000..8beb81ba
--- /dev/null
+++ b/server/src/lib/endpoint-scope.ts
@@ -0,0 +1,109 @@
+// ── Endpoint identity for custom relay models (#651) ────────────────────────
+//
+// Every custom relay is stored under platform = 'custom', so two relays that
+// both offer `deepseek-v3.1` used to collapse into ONE `models` row: one
+// enabled flag, one reliability/speed bucket, one binding anchor. Disabling the
+// model because relay A was broken disabled it for relay B too, and relay A's
+// timeouts dragged down the copy relay B served just fine (#619).
+//
+// The discriminator is `models.endpoint_scope`: the normalized base_url of the
+// endpoint the row belongs to, '' for every catalog platform. Uniqueness is
+// (platform, model_id, endpoint_scope), so catalog rows keep exactly their old
+// (platform, model_id) semantics — '' is the same value for all of them — while
+// two relays can each hold their own row for the same model id.
+//
+// Why base_url and not key_id: #640 settled that an endpoint is a base_url
+// holding a POOL of credentials, and a model rotates across that pool. Keying
+// identity on key_id would split one relay's model into one row per credential
+// and undo that. Why a TEXT token and not a foreign key: the scope is opaque to
+// everything except this module, so the per-key model groups of #657 can later
+// refine it (`<base_url>#<group>`) without a second identity migration.
+
+import type { Db } from '../db/types.js';
+
+/** Trailing-slash-insensitive endpoint identity, matching how base_url is stored. */
+export function normalizeBaseUrl(raw: string): string {
+ return raw.trim().replace(/\/+$/, '');
+}
+
+/** The scope token for a custom endpoint; '' means "not endpoint-scoped". */
+export function endpointScopeForBaseUrl(baseUrl: string | null | undefined): string {
+ return baseUrl ? normalizeBaseUrl(baseUrl) : '';
+}
+
+/**
+ * The scope a model bound to `keyId` belongs to. '' when the key is gone or
+ * carries no base_url — a legacy custom row that predates per-endpoint binding
+ * keeps the un-scoped identity it has always had, so nothing about it changes.
+ */
+export function endpointScopeOfKey(db: Db, keyId: number | null | undefined): string {
+ if (keyId == null) return '';
+ const row = db.prepare("SELECT base_url FROM api_keys WHERE id = ? AND platform = 'custom'")
+ .get(keyId) as { base_url: string | null } | undefined;
+ return endpointScopeForBaseUrl(row?.base_url);
+}
+
+/**
+ * A short, typable handle for a scope, used only for naming: the host (with
+ * port) plus path, slugified. Derived purely from the scope, so it is stable —
+ * adding or removing OTHER endpoints never renames an existing one.
+ *
+ * https://relay-a.example.com/v1 → relay-a.example.com-v1
+ * http://127.0.0.1:11434/v1 → 127.0.0.1-11434-v1
+ */
+export function endpointHandle(scope: string): string {
+ const withoutScheme = scope.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+ const slug = withoutScheme
+ .toLowerCase()
+ .replace(/[^a-z0-9.]+/g, '-')
+ .replace(/-+/g, '-')
+ .replace(/^[-.]+|[-.]+$/g, '');
+ return slug || 'endpoint';
+}
+
+/**
+ * The bucket key for reliability/speed stats and the routing round-robin.
+ * Unchanged (`platform:model_id`) for every catalog model and for un-scoped
+ * legacy custom rows; endpoint-qualified only for rows that actually carry a
+ * scope, so a single-endpoint install keeps its existing history verbatim.
+ */
+export function modelStatsKey(
+ platform: string,
+ modelId: string,
+ endpointScope: string | null | undefined,
+): string {
+ return endpointScope ? `${platform}:${modelId}@${endpointScope}` : `${platform}:${modelId}`;
+}
+
+// The separator between a member id and its endpoint handle. '#' reads as a
+// fragment and — unlike ':', '@' or '/' — does not occur in provider model ids.
+export const ENDPOINT_ID_SEPARATOR = '#';
+
+/**
+ * The endpoint-qualified model id a client can send to pin ONE relay's copy:
+ * `custom:deepseek-v3.1#relay-a.example.com-v1`. Null for rows with no scope,
+ * whose plain `platform:model_id` member id is already unambiguous — which is
+ * why a single-endpoint install never sees a qualified id anywhere.
+ */
+export function qualifiedModelMemberId(
+ platform: string,
+ modelId: string,
+ endpointScope: string | null | undefined,
+): string | null {
+ if (!endpointScope) return null;
+ return `${platform}:${modelId}${ENDPOINT_ID_SEPARATOR}${endpointHandle(endpointScope)}`;
+}
+
+/**
+ * Whether `requested` names this row's endpoint after the separator. Accepts
+ * the handle or the raw base_url (with or without scheme / trailing slash), so
+ * a user who pastes the endpoint URL they typed into the dashboard is right.
+ */
+export function endpointRefMatches(requested: string, endpointScope: string): boolean {
+ const ref = requested.trim();
+ if (!ref || !endpointScope) return false;
+ // Slugifying BOTH sides is what makes the handle and the raw URL equivalent:
+ // endpointHandle is idempotent, so handle→handle and url→handle both land on
+ // the same token.
+ return endpointHandle(ref) === endpointHandle(endpointScope);
+}
diff --git a/server/src/lib/inbound-chat.ts b/server/src/lib/inbound-chat.ts
index 4da58a5f..79b1e48b 100644
--- a/server/src/lib/inbound-chat.ts
+++ b/server/src/lib/inbound-chat.ts
@@ -17,7 +17,7 @@ import {
import {
getModelGroups,
isUnifyEnabled,
- resolveRequestedIdToMembers,
+ resolveRequestedIdForDispatch,
} from '../services/model-groups.js';
import {
newFallbackState,
@@ -116,11 +116,12 @@ function resolvePin(model: string | undefined, messages: ChatMessage[], sessionI
}
const db = getDb();
- const members = isUnifyEnabled()
- ? resolveRequestedIdToMembers(requested, getModelGroups())
+ const resolved = isUnifyEnabled()
+ ? resolveRequestedIdForDispatch(requested, getModelGroups())
: null;
+ const members = resolved?.memberDbIds ?? null;
if (members?.length) {
- const strictChain = resolveModelGroupCandidates(members);
+ const strictChain = resolveModelGroupCandidates(members, resolved!.demotedDbIds);
if (strictChain.length === 0) {
const err = new Error(`Model '${requested}' has no enabled provider with a usable key`) as Error & { status?: number; code?: string };
err.status = 503;
diff --git a/server/src/routes/fallback.ts b/server/src/routes/fallback.ts
index e0a3060a..4804146c 100644
--- a/server/src/routes/fallback.ts
+++ b/server/src/routes/fallback.ts
@@ -13,6 +13,7 @@ import { parseBudget } from '../lib/budget.js';
import { getModelGroups } from '../services/model-groups.js';
import { getPenaltyInspector } from '../services/penalty-inspector.js';
import { getActiveProfileId } from '../services/profile-models.js';
+import { qualifiedModelMemberId } from '../lib/endpoint-scope.js';
import { overriddenFieldNames } from '../services/model-state.js';
export const fallbackRouter = Router();
@@ -72,7 +73,7 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {
m.speed_rank, m.size_label, m.rpm_limit, m.rpd_limit,
m.tpm_limit, m.tpd_limit, m.context_window,
m.monthly_token_budget, m.supports_vision, m.supports_tools,
- m.key_id, ak.label AS key_label,
+ m.key_id, m.endpoint_scope, ak.label AS key_label,
mo.overrides_json IS NOT NULL AS has_overrides,
mo.overrides_json,
ts.source AS tombstone_source, ts.reason AS tombstone_reason
@@ -93,7 +94,7 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {
m.speed_rank, m.size_label, m.rpm_limit, m.rpd_limit,
m.tpm_limit, m.tpd_limit, m.context_window,
m.monthly_token_budget, m.supports_vision, m.supports_tools,
- m.key_id, ak.label AS key_label,
+ m.key_id, m.endpoint_scope, ak.label AS key_label,
mo.overrides_json IS NOT NULL AS has_overrides,
mo.overrides_json,
ts.source AS tombstone_source, ts.reason AS tombstone_reason
@@ -168,6 +169,14 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {
source: r.platform === 'custom' || r.key_id != null ? 'custom' : 'catalog',
keyId: r.key_id ?? null,
keyLabel: r.key_label ?? null,
+ // Which relay endpoint a custom row belongs to, and the id that names it
+ // unambiguously (#651). Null for catalog models only — every custom row
+ // bound to an endpoint carries both, including a lone one. Deciding when
+ // they are worth showing is the client's job (see memberProviderLabel /
+ // providerPinId / memberEndpointTitle): it reveals them only where two
+ // endpoints actually serve the same model id.
+ endpointScope: r.endpoint_scope || null,
+ qualifiedModelId: qualifiedModelMemberId(r.platform, r.model_id, r.endpoint_scope),
hasOverrides: Boolean(r.has_overrides),
// Which fields the local override actually replaces, so the model page
// can mark the individual inputs it edits (#551).
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index d9bcb942..8008df9c 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -13,6 +13,7 @@ import { getActiveCooldownsForKeys, clearCooldownsForKey } from '../services/rat
import { resolveCustomEndpointKey, customEndpointKeyIds, siblingEndpointKeyId } from '../services/custom-endpoint.js';
import { customModelSeed } from '../services/custom-model-seed.js';
import { discoverEndpointModels, ModelDiscoveryError } from '../services/model-discovery.js';
+import { endpointScopeForBaseUrl, normalizeBaseUrl } from '../lib/endpoint-scope.js';
export const keysRouter = Router();
@@ -500,8 +501,6 @@ const customProviderSchema = z.object({
{ message: 'baseUrl or keyId is required' },
);
-const normalizeBaseUrl = (raw: string) => raw.trim().replace(/\/+$/, '');
-
interface CustomEndpointRef {
baseUrl: string;
/** The api_keys row this endpoint is already stored under, or null when the
@@ -701,6 +700,8 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
db, baseUrl, providedKey, label, endpoint.keyId ?? undefined,
);
const endpointKeyIds = customEndpointKeyIds(db, keyId);
+ // The identity discriminator for every row registered in this call (#651).
+ const endpointScope = endpointScopeForBaseUrl(baseUrl);
// Unknown ≠ worst: seed the routing ranks at the catalog median so a new
// custom model is explored instead of buried at intelligence 0 (#488).
const seed = customModelSeed(db);
@@ -709,15 +710,17 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
for (const { modelId, displayName, supportsTools, supportsVision } of entries) {
// Register each model bound to THIS endpoint's key. Custom models carry no
// rate limits and sort last in the intelligence preset (size_label tier).
- // Re-registering an existing model id re-binds it to the submitted
- // ENDPOINT (model ids are unique per platform, so one id can't live on two
- // endpoints at once) — but a model already on this endpoint keeps the key
- // it has, so adding a second credential doesn't silently re-bind it (#619).
+ // Identity is per endpoint (#651): the same model id on a DIFFERENT relay
+ // is a separate row with its own enabled flag, ranks and stats, instead of
+ // silently rebinding the other endpoint's row as it used to. A model
+ // already on THIS endpoint keeps the key it has, so adding a second
+ // credential doesn't re-bind it (#619).
// Capability flags: an unset flag binds NULL so COALESCE picks the insert
// default (tools 1, vision 0) on a new row and preserves the existing
// value on re-registration. (#470)
- const bound = db.prepare("SELECT key_id FROM models WHERE platform = 'custom' AND model_id = ?")
- .get(modelId) as { key_id: number | null } | undefined;
+ const bound = db.prepare(
+ "SELECT key_id FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
+ ).get(modelId, endpointScope) as { key_id: number | null } | undefined;
const created = bound === undefined;
const bindKeyId = bound?.key_id != null && endpointKeyIds.has(bound.key_id) ? bound.key_id : keyId;
const toolsParam = supportsTools === undefined ? null : (supportsTools ? 1 : 0);
@@ -729,11 +732,11 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
INSERT INTO models
(platform, model_id, display_name, intelligence_rank, speed_rank, size_label,
rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window, enabled, key_id,
- supports_tools, supports_vision, source)
+ supports_tools, supports_vision, source, endpoint_scope)
VALUES ('custom', @modelId, @displayName, @intelligenceRank, @speedRank, @sizeLabel,
NULL, NULL, NULL, NULL, '', NULL, 1, @keyId,
- COALESCE(@tools, 1), COALESCE(@vision, 0), 'user')
- ON CONFLICT(platform, model_id)
+ COALESCE(@tools, 1), COALESCE(@vision, 0), 'user', @endpointScope)
+ ON CONFLICT(platform, model_id, endpoint_scope)
DO UPDATE SET
display_name = excluded.display_name,
key_id = excluded.key_id,
@@ -743,9 +746,12 @@ keysRouter.post('/custom', async (req: Request, res: Response) => {
`).run({
modelId, displayName, keyId: bindKeyId, tools: toolsParam, vision: visionParam,
intelligenceRank: seed.intelligenceRank, speedRank: seed.speedRank, sizeLabel: seed.sizeLabel,
+ endpointScope,
});
- const modelRow = db.prepare("SELECT id, supports_tools, supports_vision FROM models WHERE platform = 'custom' AND model_id = ?").get(modelId) as { id: number; supports_tools: number; supports_vision: number };
+ const modelRow = db.prepare(
+ "SELECT id, supports_tools, supports_vision FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
+ ).get(modelId, endpointScope) as { id: number; supports_tools: number; supports_vision: number };
// Append to the fallback chain if not already present.
const inChain = db.prepare('SELECT 1 FROM fallback_config WHERE model_db_id = ?').get(modelRow.id);
diff --git a/server/src/routes/models.ts b/server/src/routes/models.ts
index cf8bd0d4..e0bbec7d 100644
--- a/server/src/routes/models.ts
+++ b/server/src/routes/models.ts
@@ -13,6 +13,7 @@ import {
} from '../services/model-state.js';
import { pruneUnavailableSavedFusionConfig } from '../services/fusion.js';
import { getActiveProfileId } from '../services/profile-models.js';
+import { qualifiedModelMemberId } from '../lib/endpoint-scope.js';
export const modelsRouter = Router();
@@ -257,6 +258,10 @@ modelsRouter.get('/', (_req: Request, res: Response) => {
source: m.source === 'user' ? 'custom' : 'catalog',
keyId: m.key_id ?? null,
keyLabel: m.key_label ?? null,
+ // Endpoint identity for custom rows (#651); null for catalog models and for
+ // custom rows that carry no endpoint scope.
+ endpointScope: m.endpoint_scope || null,
+ qualifiedModelId: qualifiedModelMemberId(m.platform, m.model_id, m.endpoint_scope),
hasOverrides: Boolean(m.has_overrides),
overrideFields: overriddenFieldNames(m.overrides_json),
hasProvider: hasProvider(m.platform),
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 5fd6512e..e1a0e6f7 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -26,7 +26,7 @@ import { samplingParamSchemaFields, pickSamplingParams, supportedParametersForPl
import { enforceJsonContent } from '../lib/structured-output.js';
import type { Platform } from '@freellmapi/shared/types.js';
import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';
-import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';
+import { isUnifyEnabled, getModelGroups, resolveRequestedIdForDispatch } from '../services/model-groups.js';
import { buildModelListing } from '../services/model-listing.js';
import { compressRequest, formatCompressionHeader } from '../services/compression/pipeline.js';
@@ -820,9 +820,10 @@ proxyRouter.post('/completions', async (req: Request, res: Response) => {
if (!isAutoModel(requestedModel) && requestedModel) {
const db = getDb();
- const members = isUnifyEnabled() ? resolveRequestedIdToMembers(requestedModel, getModelGroups()) : null;
+ const resolved = isUnifyEnabled() ? resolveRequestedIdForDispatch(requestedModel, getModelGroups()) : null;
+ const members = resolved?.memberDbIds ?? null;
if (members && members.length > 0) {
- groupChain = resolveModelGroupCandidates(members);
+ groupChain = resolveModelGroupCandidates(members, resolved!.demotedDbIds);
if (groupChain.length === 0) {
const placeholders = members.map(() => '?').join(',');
const anyEnabled = db.prepare(`SELECT 1 FROM models WHERE id IN (${placeholders}) AND enabled = 1 LIMIT 1`).get(...members);
@@ -1569,9 +1570,10 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
// Unify ON: a requested id (canonical slug OR any provider's model_id) maps
// to the whole logical-model group, and we route STRICTLY across only its
// providers — failing over between them, never to a different model (#335).
- const members = isUnifyEnabled() ? resolveRequestedIdToMembers(requestedModel, getModelGroups()) : null;
+ const resolved = isUnifyEnabled() ? resolveRequestedIdForDispatch(requestedModel, getModelGroups()) : null;
+ const members = resolved?.memberDbIds ?? null;
if (members && members.length > 0) {
- groupChain = resolveModelGroupCandidates(members);
+ groupChain = resolveModelGroupCandidates(members, resolved!.demotedDbIds);
if (groupChain.length === 0) {
// Distinguish a catalog-disabled model (404 model_not_found, OpenAI
// semantics) from one whose providers are present but unusable
diff --git a/server/src/routes/responses.ts b/server/src/routes/responses.ts
index e4ba2a50..c53a615d 100644
--- a/server/src/routes/responses.ts
+++ b/server/src/routes/responses.ts
@@ -11,7 +11,7 @@ import type {
} from '@freellmapi/shared/types.js';
import { routeRequest, hasEnabledToolsModel, resolveStickyPreference, routingReserveTokens, resolveModelGroupCandidates, type RouteResult, type ChainRow } from '../services/router.js';
import { getDb, getUnifiedApiKey } from '../db/index.js';
-import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';
+import { isUnifyEnabled, getModelGroups, resolveRequestedIdForDispatch } from '../services/model-groups.js';
import { contentToString } from '../lib/content.js';
import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';
import { rescueInlineToolCalls, startsWithDialectMarker, couldBecomeDialectMarker, containsDialectMarker } from '../lib/tool-call-rescue.js';
@@ -424,9 +424,10 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {
preferredModel = resolveStickyPreference(getStickyModel(messages, sessionIdHeader));
} else {
const db = getDb();
- const members = isUnifyEnabled() ? resolveRequestedIdToMembers(requestedModelLabel, getModelGroups()) : null;
+ const resolved = isUnifyEnabled() ? resolveRequestedIdForDispatch(requestedModelLabel, getModelGroups()) : null;
+ const members = resolved?.memberDbIds ?? null;
if (members && members.length > 0) {
- groupChain = resolveModelGroupCandidates(members);
+ groupChain = resolveModelGroupCandidates(members, resolved!.demotedDbIds);
if (groupChain.length === 0) {
const placeholders = members.map(() => '?').join(',');
const anyEnabled = db.prepare(`SELECT 1 FROM models WHERE id IN (${placeholders}) AND enabled = 1 LIMIT 1`).get(...members);
diff --git a/server/src/services/declarative-config.ts b/server/src/services/declarative-config.ts
index 20df5c8f..eee2a64c 100644
--- a/server/src/services/declarative-config.ts
+++ b/server/src/services/declarative-config.ts
@@ -7,6 +7,7 @@ import { resolveProvider } from '../providers/index.js';
import { setCustomWeights, setRoutingStrategy } from './router.js';
import { ensureModelInProfiles } from './profile-models.js';
import { customModelSeed } from './custom-model-seed.js';
+import { endpointRefMatches, endpointScopeForBaseUrl } from '../lib/endpoint-scope.js';
import {
clearCatalogModelTombstone,
isCatalogManagedModel,
@@ -48,6 +49,10 @@ const customProviderSchema = z.object({
const modelSchema = z.object({
platform: z.string().min(1),
modelId: z.string().min(1),
+ // Which custom endpoint this entry means, when several serve the same model
+ // id (#651). Accepts the endpoint URL or its short handle. Ignored for
+ // catalog platforms, where (platform, modelId) is already unique.
+ endpoint: z.string().min(1).optional(),
displayName: z.string().min(1).optional(),
intelligenceRank: z.number().int().min(1).max(1000).optional(),
speedRank: z.number().int().min(1).max(1000).optional(),
@@ -67,6 +72,7 @@ const modelSchema = z.object({
const fallbackEntrySchema = z.object({
platform: z.string().min(1),
modelId: z.string().min(1),
+ endpoint: z.string().min(1).optional(),
priority: z.number().int().positive().optional(),
enabled: z.boolean().optional(),
});
@@ -230,6 +236,10 @@ function registerCustomProvider(db: Db, input: z.infer<typeof customProviderSche
// undeclared rank means "unknown", not "worst". An explicitly declared rank
// always wins.
const seed = customModelSeed(db);
+ // Model identity is per endpoint (#651): declaring the same model id under a
+ // second base_url adds a row for that endpoint instead of stealing the first
+ // one's.
+ const endpointScope = endpointScopeForBaseUrl(input.baseUrl);
let registered = 0;
for (const entry of input.models) {
const model = normalizeModelEntry(entry);
@@ -237,9 +247,9 @@ function registerCustomProvider(db: Db, input: z.infer<typeof customProviderSche
INSERT INTO models
(platform, model_id, display_name, intelligence_rank, speed_rank, size_label,
rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window,
- enabled, supports_vision, supports_tools, key_id, source)
- VALUES ('custom', ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, 1, ?, ?, ?, 'user')
- ON CONFLICT(platform, model_id)
+ enabled, supports_vision, supports_tools, key_id, source, endpoint_scope)
+ VALUES ('custom', ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, 1, ?, ?, ?, 'user', ?)
+ ON CONFLICT(platform, model_id, endpoint_scope)
DO UPDATE SET
display_name = excluded.display_name,
intelligence_rank = excluded.intelligence_rank,
@@ -262,8 +272,11 @@ function registerCustomProvider(db: Db, input: z.infer<typeof customProviderSche
model.supportsVision ? 1 : 0,
model.supportsTools ? 1 : 0,
keyId,
+ endpointScope,
);
- const row = db.prepare("SELECT id FROM models WHERE platform = 'custom' AND model_id = ?").get(model.modelId) as { id: number };
+ const row = db.prepare(
+ "SELECT id FROM models WHERE platform = 'custom' AND model_id = ? AND endpoint_scope = ?",
+ ).get(model.modelId, endpointScope) as { id: number };
ensureFallbackRow(db, row.id, model.fallbackEnabled !== false);
registered++;
}
@@ -282,12 +295,62 @@ function modelPatchFromInput(input: z.infer<typeof modelSchema>): ModelOverrideP
return patch;
}
+interface DeclaredModelRow {
+ id: number;
+ platform: string;
+ model_id: string;
+ key_id: number | null;
+ source: string;
+ endpoint_scope: string;
+}
+
+/**
+ * The ONE models row a declarative entry names, or undefined when there is no
+ * such model yet.
+ *
+ * For catalog platforms this is the old lookup: (platform, model_id) is unique,
+ * so nothing changes. For 'custom' two relays can hold the same model id
+ * (#651), and `SELECT ... LIMIT 1` would patch whichever row the query happened
+ * to return — silently editing the wrong relay. So an ambiguous entry is
+ * refused, and the config author gets the endpoints to choose from.
+ */
+function resolveDeclaredModel(
+ db: Db,
+ platform: string,
+ modelId: string,
+ endpoint: string | undefined,
+): DeclaredModelRow | undefined {
+ const rows = db.prepare(
+ 'SELECT id, platform, model_id, key_id, source, endpoint_scope FROM models WHERE platform = ? AND model_id = ? ORDER BY id',
+ ).all(platform, modelId) as DeclaredModelRow[];
+
+ if (endpoint) {
+ const named = rows.filter(r => r.endpoint_scope && endpointRefMatches(endpoint, r.endpoint_scope));
+ if (named.length === 1) return named[0];
+ if (named.length === 0) {
+ throw new Error(
+ `${platform}/${modelId}: no custom endpoint matching '${endpoint}' serves this model` +
+ `${rows.length > 0 ? ` (known: ${rows.map(r => r.endpoint_scope || '(none)').join(', ')})` : ''}. ` +
+ 'A "models" entry edits a model that already exists — register it under "customProviders" first.',
+ );
+ }
+ throw new Error(`${platform}/${modelId}: endpoint '${endpoint}' matches more than one endpoint`);
+ }
+
+ if (rows.length > 1) {
+ throw new Error(
+ `${platform}/${modelId} exists on more than one endpoint — add an "endpoint" to say which one ` +
+ `(${rows.map(r => r.endpoint_scope || '(none)').join(', ')})`,
+ );
+ }
+ return rows[0];
+}
+
function upsertModel(db: Db, input: z.infer<typeof modelSchema>): void {
const platform = input.platform.trim();
const modelId = input.modelId.trim();
clearCatalogModelTombstone(db, 'chat', platform, modelId);
- const existing = db.prepare('SELECT id, platform, model_id, key_id, source FROM models WHERE platform = ? AND model_id = ?')
- .get(platform, modelId) as { id: number; platform: string; model_id: string; key_id: number | null; source: string } | undefined;
+ const existing = resolveDeclaredModel(db, platform, modelId, input.endpoint);
if (!existing) {
// A declaratively-created model is user-owned: catalog sync must never
@@ -362,8 +425,7 @@ function applyFallback(db: Db, entries: z.infer<typeof fallbackEntrySchema>[]):
const update = db.prepare('UPDATE fallback_config SET priority = ?, enabled = ? WHERE model_db_id = ?');
let changed = 0;
entries.forEach((entry, i) => {
- const row = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?')
- .get(entry.platform, entry.modelId) as { id: number } | undefined;
+ const row = resolveDeclaredModel(db, entry.platform, entry.modelId, entry.endpoint);
if (!row) return;
ensureFallbackRow(db, row.id, entry.enabled !== false);
update.run(entry.priority ?? i + 1, entry.enabled === false ? 0 : 1, row.id);
diff --git a/server/src/services/model-groups.ts b/server/src/services/model-groups.ts
index 7c266723..9417ae45 100644
--- a/server/src/services/model-groups.ts
+++ b/server/src/services/model-groups.ts
@@ -15,6 +15,11 @@
*/
import { z } from 'zod';
import { getDb, getSetting, setSetting } from '../db/index.js';
+import {
+ ENDPOINT_ID_SEPARATOR,
+ endpointRefMatches,
+ qualifiedModelMemberId,
+} from '../lib/endpoint-scope.js';
// ── Settings keys ────────────────────────────────────────────────────────────
export const UNIFY_ENABLED_KEY = 'unify_models_enabled';
@@ -48,6 +53,20 @@ export interface GroupableRow {
model_id: string;
display_name: string;
intelligence_rank?: number;
+ // Which custom endpoint this row belongs to; '' (or absent) for every catalog
+ // platform and for legacy un-scoped custom rows (#651).
+ endpoint_scope?: string;
+}
+
+/**
+ * How a resolved member was reached: by its own model_id (or a group the
+ * operator built), versus only through a group's auto-derived slug.
+ */
+export type MatchTier = 'literal' | 'slug';
+
+export interface TieredMember {
+ modelDbId: number;
+ tier: MatchTier;
}
export interface ModelGroup {
@@ -55,6 +74,11 @@ export interface ModelGroup {
canonicalId: string; // stable slug advertised on /v1/models
groupLabel: string; // human label = representative member's stripped name
members: GroupableRow[]; // all rows in the group (any enabled state)
+ // True when an operator override (a merge or an explicit group key) put this
+ // group together, rather than the catalog's display names doing it by
+ // accident. A slug match on a name the user asserted themselves is a
+ // first-class answer; one on an auto-derived slug is only a fallback.
+ userDefined: boolean;
}
// ── Settings accessors ───────────────────────────────────────────────────────
@@ -133,18 +157,43 @@ function memberId(row: GroupableRow): string {
return `${row.platform}:${row.model_id}`;
}
+/**
+ * The endpoint-qualified member id, or null when the row needs no qualifier.
+ * Only custom rows that actually carry an endpoint scope have one, which is why
+ * an install with a single relay never sees a qualified id anywhere (#651).
+ */
+export function qualifiedMemberId(row: GroupableRow): string | null {
+ return qualifiedModelMemberId(row.platform, row.model_id, row.endpoint_scope);
+}
+
// The grouping token for a row, after applying overrides. Split wins first
// (forces a singleton/explicit key); then a merge redirects to its target;
// otherwise the normalized display name.
function tokenForRow(row: GroupableRow, ov: UnifyOverrides): string {
+ return tokenSourceForRow(row, ov).token;
+}
+
+/** The grouping token plus whether an operator override chose it. */
+function tokenSourceForRow(row: GroupableRow, ov: UnifyOverrides): { token: string; userDefined: boolean } {
const mid = memberId(row);
+ // A qualified id names ONE relay's copy, so an override written against it
+ // must only move that copy. Plain member ids keep matching as before, which is
+ // what makes existing overrides survive untouched.
+ const qid = qualifiedMemberId(row);
+ const names = (candidate: string) => candidate === mid || (qid !== null && candidate === qid);
- const split = ov.splits.find(s => s.member === mid);
- if (split) return split.groupKey ? normalizeGroupKey(split.groupKey) : `__split__:${mid}`;
+ const split = ov.splits.find(s => names(s.member));
+ if (split) {
+ return split.groupKey
+ ? { token: normalizeGroupKey(split.groupKey), userDefined: true }
+ : { token: `__split__:${split.member}`, userDefined: true };
+ }
const base = normalizeGroupKey(row.display_name);
- const merge = ov.merges.find(mg => mg.keys.some(k => k === mid || normalizeGroupKey(k) === base));
- return merge ? normalizeGroupKey(merge.into) : base;
+ const merge = ov.merges.find(mg => mg.keys.some(k => names(k) || normalizeGroupKey(k) === base));
+ return merge
+ ? { token: normalizeGroupKey(merge.into), userDefined: true }
+ : { token: base, userDefined: false };
}
// Assign a unique canonicalId to each group. Deterministic: groups sorted by
@@ -168,13 +217,17 @@ function assignCanonicalIds(groups: ModelGroup[]): void {
export function groupRows(rows: GroupableRow[], ov: UnifyOverrides): ModelGroup[] {
const map = new Map<string, ModelGroup>();
for (const row of rows) {
- const key = tokenForRow(row, ov);
+ const { token: key, userDefined } = tokenSourceForRow(row, ov);
let g = map.get(key);
if (!g) {
- g = { groupKey: key, canonicalId: '', groupLabel: stripProviderSuffix(row.display_name), members: [] };
+ g = {
+ groupKey: key, canonicalId: '', groupLabel: stripProviderSuffix(row.display_name),
+ members: [], userDefined: false,
+ };
map.set(key, g);
}
g.members.push(row);
+ g.userDefined ||= userDefined;
}
// Representative label = the best (lowest intelligence_rank) member, tiebroken
@@ -194,34 +247,116 @@ export function groupRows(rows: GroupableRow[], ov: UnifyOverrides): ModelGroup[
/**
* Resolve a requested model id to the db ids of its group members, or null.
- * Accepts the canonical slug OR any member's `model_id` (back-compat: an old
- * per-provider id resolves to the whole group), OR the fully-qualified
- * "platform:model_id" member id — which HARD-PINS to only that member (#580):
- * spelling out the platform is an explicit "this provider's copy" request, so
- * it must not fail over to (or share scores with) the rest of the group.
- * Member order here is incidental — the router re-orders by the active
- * strategy.
+ *
+ * The ladder, most specific first:
+ * 1. "custom:model_id#endpoint" → exactly that relay's copy (#651) — the only
+ * form that can separate two endpoints offering the same model id. The
+ * endpoint part accepts the short handle or the endpoint URL itself;
+ * 2. "platform:model_id" → that platform's copies. Normally exactly one row,
+ * so this is unchanged (#580: naming the platform means "this provider's
+ * copy", no failover to the rest of the group). Two relays sharing a model
+ * id are both 'custom', so this names both and the router picks the better
+ * one — nothing an existing setup can notice, and no error to hit;
+ * 3. a canonical group slug OR a bare `model_id` → the union of every group
+ * that answers to it. Display name is presentation, not identity: it may
+ * EXPAND what a bare id reaches (that is the unify feature — one name,
+ * several providers) but it must never SHRINK it. Renaming one relay's
+ * copy, or splitting it out for display, moves it to its own group;
+ * stopping at the first match would strand the other relay, unreachable by
+ * the id every client already has (#651).
+ *
+ * Member order here is incidental — the router re-orders by the active strategy.
*/
-export function resolveRequestedIdToMembers(requested: string, groups: ModelGroup[]): number[] | null {
+export function resolveRequestedIdToTieredMembers(requested: string, groups: ModelGroup[]): TieredMember[] | null {
if (!requested) return null;
- const byCanonical = groups.find(g => g.canonicalId === requested);
- if (byCanonical) return byCanonical.members.map(m => m.model_db_id);
+ const sepAt = requested.lastIndexOf(ENDPOINT_ID_SEPARATOR);
+ if (sepAt > 0) {
+ const base = requested.slice(0, sepAt);
+ const endpointRef = requested.slice(sepAt + 1);
+ for (const g of groups) {
+ for (const m of g.members) {
+ if (memberId(m) !== base) continue;
+ if (m.endpoint_scope && endpointRefMatches(endpointRef, m.endpoint_scope)) {
+ return [{ modelDbId: m.model_db_id, tier: 'literal' }];
+ }
+ }
+ }
+ }
- // Exact "platform:model_id" → just that member. Checked before the bare
- // model_id scan; a bare model_id that itself contains a colon (e.g. Ollama's
- // "gpt-oss:120b") never collides because platforms aren't model-name prefixes.
- for (const g of groups) {
- const exact = g.members.find(m => memberId(m) === requested);
- if (exact) return [exact.model_db_id];
+ // Exact "platform:model_id". Checked before the bare model_id scan; a bare
+ // model_id that itself contains a colon (e.g. Ollama's "gpt-oss:120b") never
+ // collides because platforms aren't model-name prefixes.
+ const exact = groups.flatMap(g => g.members.filter(m => memberId(m) === requested));
+ if (exact.length > 0) {
+ return exact.map(m => ({ modelDbId: m.model_db_id, tier: 'literal' as MatchTier }));
}
+ // Canonical slug and bare model id resolve TOGETHER, as an ORDERED union.
+ //
+ // Keeping them as separate early-returns let a slug shadow the id: rename one
+ // relay's copy and its group's slug is no longer 'deepseek-v3.1', while the
+ // untouched relay's group still slugs to exactly that — so the bare id matched
+ // one group by slug, returned early, and the renamed relay became unreachable.
+ //
+ // But the two matches are not equally intended. A canonicalId is a SLUG of a
+ // display name, so it can coincide with an unrelated model's literal id (the
+ // shipped catalog has one: Cloudflare's "Gemma 4 26B-A4B it" slugs to
+ // `gemma-4-26b-a4b-it`, Google's literal model_id in another group). A request
+ // written literally must therefore try the literal model FIRST; a coincidental
+ // slug sibling is a fallback that may serve only once the real one is
+ // exhausted. Groups the operator built by hand rank with the literal matches —
+ // they asserted that name themselves.
+ const literal: TieredMember[] = [];
+ const slugOnly: TieredMember[] = [];
+ const seen = new Set<number>();
for (const g of groups) {
- if (g.members.some(m => m.model_id === requested)) {
- return g.members.map(m => m.model_db_id);
+ const byMember = g.members.some(m => m.model_id === requested);
+ if (!byMember && g.canonicalId !== requested) continue;
+ const bucket = byMember || g.userDefined ? literal : slugOnly;
+ const tier: MatchTier = bucket === literal ? 'literal' : 'slug';
+ for (const m of g.members) {
+ if (seen.has(m.model_db_id)) continue;
+ seen.add(m.model_db_id);
+ bucket.push({ modelDbId: m.model_db_id, tier });
}
}
- return null;
+ const matched = [...literal, ...slugOnly];
+ return matched.length > 0 ? matched : null;
+}
+
+/**
+ * The same resolution, flattened to db ids in tier order. Callers that dispatch
+ * a request should prefer the tiered form and pass `demotedMemberIds()` to the
+ * router, so a fallback match cannot outrank a literal one on score alone.
+ */
+export function resolveRequestedIdToMembers(requested: string, groups: ModelGroup[]): number[] | null {
+ return resolveRequestedIdToTieredMembers(requested, groups)?.map(m => m.modelDbId) ?? null;
+}
+
+/** The subset of a tiered resolution that was reached only through a slug. */
+export function demotedMemberIds(members: readonly TieredMember[]): Set<number> {
+ return new Set(members.filter(m => m.tier === 'slug').map(m => m.modelDbId));
+}
+
+export interface DispatchMembers {
+ /** Every member, in tier order. */
+ memberDbIds: number[];
+ /** Those of them that are fallbacks — hand this to resolveModelGroupCandidates. */
+ demotedDbIds: Set<number>;
+}
+
+/**
+ * One-call resolution for the request path: the member ids to route over plus
+ * the ones that must not outrank a literal match on score (#651).
+ */
+export function resolveRequestedIdForDispatch(
+ requested: string,
+ groups: ModelGroup[],
+): DispatchMembers | null {
+ const tiered = resolveRequestedIdToTieredMembers(requested, groups);
+ if (!tiered) return null;
+ return { memberDbIds: tiered.map(m => m.modelDbId), demotedDbIds: demotedMemberIds(tiered) };
}
// ── DB convenience ───────────────────────────────────────────────────────────
@@ -232,8 +367,10 @@ export function resolveRequestedIdToMembers(requested: string, groups: ModelGrou
export function getModelGroups(): ModelGroup[] {
const db = getDb();
const rows = db.prepare(`
- SELECT m.id as model_db_id, m.platform, m.model_id, m.display_name, m.intelligence_rank
+ SELECT m.id as model_db_id, m.platform, m.model_id, m.display_name, m.intelligence_rank,
+ m.endpoint_scope
FROM models m
+ ORDER BY m.id
`).all() as GroupableRow[];
return groupRows(rows, getUnifyOverrides());
}
diff --git a/server/src/services/model-retirement.ts b/server/src/services/model-retirement.ts
index d1e2dfca..434f9ce4 100644
--- a/server/src/services/model-retirement.ts
+++ b/server/src/services/model-retirement.ts
@@ -17,6 +17,7 @@ import { getDb } from '../db/index.js';
import { modelRetirementSignal } from '../lib/error-classify.js';
import { summarizeAttemptError } from '../lib/error-redaction.js';
import { isCatalogManagedModel, retireCatalogModelUpstream } from './model-state.js';
+import { modelStatsKey } from '../lib/endpoint-scope.js';
/** How many DISTINCT requests must report a 'probable' signal before acting. */
export const RETIREMENT_CONFIRMATIONS_REQUIRED = 2;
@@ -46,6 +47,13 @@ export interface RetirementRoute {
modelDbId: number;
platform: string;
modelId: string;
+ /**
+ * The endpoint this route belongs to, for custom relays (#651). Two relays
+ * can serve the same model id; a 410 from one says nothing about the other,
+ * so their corroboration counters must not share a bucket. Absent/'' for
+ * catalog platforms, which keeps their key exactly what it always was.
+ */
+ endpointScope?: string;
}
/**
@@ -62,7 +70,7 @@ export function noteModelRetirementSignal(
const confidence = modelRetirementSignal(err);
if (!confidence) return false;
- const key = `${route.platform}:${route.modelId}`;
+ const key = modelStatsKey(route.platform, route.modelId, route.endpointScope);
if (confidence === 'probable' && !confirmObservation(key, requestToken)) return false;
const reason = summarizeAttemptError((err as { message?: unknown })?.message);
diff --git a/server/src/services/router.ts b/server/src/services/router.ts
index 455a15f1..4949fa0d 100644
--- a/server/src/services/router.ts
+++ b/server/src/services/router.ts
@@ -23,9 +23,10 @@ import { TIMEOUT_ERROR_MARKERS } from '../lib/error-classify.js';
import { modelsWithOverriddenField } from './model-state.js';
import { parseBudget } from '../lib/budget.js';
import { platformDropsResponseFormat } from '../lib/sampling-params.js';
-import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from './model-groups.js';
+import { isUnifyEnabled, getModelGroups, resolveRequestedIdForDispatch } from './model-groups.js';
import { getActiveProfileId } from './profile-models.js';
import { customEndpointKeyIds } from './custom-endpoint.js';
+import { modelStatsKey, endpointScopeForBaseUrl } from '../lib/endpoint-scope.js';
import type { BaseProvider } from '../providers/base.js';
import type { Platform } from '@freellmapi/shared/types.js';
import type { Db } from '../db/types.js';
@@ -139,6 +140,19 @@ export interface ChainRow {
// Custom models bind to the api_keys row carrying their endpoint (#212);
// NULL for built-in platforms.
key_id: number | null;
+ // The endpoint this row belongs to ('' for catalog platforms). Two relays can
+ // each hold a row for the same model_id, and everything scored or rate-limited
+ // per model has to tell them apart (#651).
+ endpoint_scope: string;
+ /**
+ * Ordering TIER, ahead of score. 0 (the default, and what every other chain
+ * builder produces) is a normal candidate. A higher number is a fallback that
+ * may only serve once every lower tier is exhausted, however good its live
+ * numbers are — currently set only for a member reached through a group's
+ * auto-derived slug rather than the model id the client actually wrote, where
+ * answering on score alone would be a silent substitution (#651).
+ */
+ match_tier?: number;
}
export interface RouteResult {
@@ -149,6 +163,12 @@ export interface RouteResult {
keyId: number;
platform: string;
displayName: string;
+ /**
+ * The custom endpoint this route belongs to, '' for catalog platforms (#651).
+ * Carried on the route so the failure path can attribute a retirement signal
+ * to ONE relay instead of every relay serving the same model id.
+ */
+ endpointScope: string;
// Daily limits for this model, so a 429 handler can tell a genuine daily
// exhaustion (escalate the cooldown) from a transient per-minute spike.
rpdLimit: number | null;
@@ -368,6 +388,9 @@ interface KeyStats {
avgTtfbMs: number | null;
}
+// Keyed by modelStatsKey(): "platform:model_id" for catalog models, and
+// "custom:model_id@base_url" for a relay model that carries an endpoint scope
+// (#651). A single-endpoint install produces the same keys it always did.
let statsCache: Map<string, ModelStats> | null = null;
let keyStatsCache: Map<string, KeyStats> | null = null; // "platform:model_id:key_id"
let statsCacheTime = 0;
@@ -386,6 +409,13 @@ const IS_TIMEOUT_SQL = `(status != 'success' AND (${
TIMEOUT_ERROR_MARKERS.map(m => `LOWER(COALESCE(error, '')) LIKE '%${m}%'`).join(' OR ')
}))`;
+/** api_keys.id → endpoint scope, for every custom credential on record (#651). */
+function customEndpointScopes(db: Db): Map<number, string> {
+ const rows = db.prepare("SELECT id, base_url FROM api_keys WHERE platform = 'custom'")
+ .all() as { id: number; base_url: string | null }[];
+ return new Map(rows.map(r => [r.id, endpointScopeForBaseUrl(r.base_url)]));
+}
+
export function refreshStatsCache(db: Db, force = false): void {
if (!force && statsCache && Date.now() - statsCacheTime < CACHE_TTL_MS) return;
@@ -434,10 +464,19 @@ export function refreshStatsCache(db: Db, force = false): void {
a.wTtfbCnt += w * (b.succ_ttfb_cnt + b.timeouts);
a.wTimeouts += w * b.timeouts;
};
+ // Which endpoint each custom credential belongs to, so a request logged
+ // against relay A's key lands in relay A's bucket and nowhere else (#651).
+ // `requests` has always recorded key_id, so pre-migration history splits
+ // correctly too; rows whose key is gone (or that never had one) fall into the
+ // un-scoped bucket, which only un-scoped rows read.
+ const scopeByKeyId = customEndpointScopes(db);
+ const scopeOf = (platform: string, keyId: number | null): string =>
+ platform === 'custom' && keyId != null ? (scopeByKeyId.get(keyId) ?? '') : '';
+
const acc = new Map<string, Acc>();
const keyAcc = new Map<string, Acc>();
for (const b of buckets) {
- const key = `${b.platform}:${b.model_id}`;
+ const key = modelStatsKey(b.platform, b.model_id, scopeOf(b.platform, b.key_id));
const w = decayWeight(b.age_days);
let a = acc.get(key);
if (!a) acc.set(key, a = emptyAcc());
@@ -452,13 +491,17 @@ export function refreshStatsCache(db: Db, force = false): void {
// Calendar-month token usage per model, for the headroom guardrail.
const usageRows = db.prepare(`
- SELECT platform, model_id, COALESCE(SUM(input_tokens + output_tokens), 0) AS used
+ SELECT platform, model_id, key_id, COALESCE(SUM(input_tokens + output_tokens), 0) AS used
FROM requests
WHERE created_at >= datetime('now', 'start of month')
AND request_type = 'chat'
- GROUP BY platform, model_id
- `).all() as Array<{ platform: string; model_id: string; used: number }>;
- const usageMap = new Map(usageRows.map(r => [`${r.platform}:${r.model_id}`, r.used]));
+ GROUP BY platform, model_id, key_id
+ `).all() as Array<{ platform: string; model_id: string; key_id: number | null; used: number }>;
+ const usageMap = new Map<string, number>();
+ for (const r of usageRows) {
+ const key = modelStatsKey(r.platform, r.model_id, scopeOf(r.platform, r.key_id));
+ usageMap.set(key, (usageMap.get(key) ?? 0) + r.used);
+ }
const next = new Map<string, ModelStats>();
for (const [key, a] of acc) {
@@ -544,16 +587,19 @@ export function writeObservedSpeedRanks(db: Db): number {
if (!statsCache || statsCache.size === 0) return 0;
const pinned = modelsWithOverriddenField(db, 'speedRank');
- const rows = db.prepare('SELECT id, platform, model_id, speed_rank FROM models')
- .all() as { id: number; platform: string; model_id: string; speed_rank: number }[];
+ const rows = db.prepare('SELECT id, platform, model_id, speed_rank, endpoint_scope FROM models')
+ .all() as { id: number; platform: string; model_id: string; speed_rank: number; endpoint_scope: string }[];
const update = db.prepare('UPDATE models SET speed_rank = ? WHERE id = ?');
let written = 0;
const tx = db.transaction(() => {
for (const row of rows) {
- const key = `${row.platform}:${row.model_id}`;
- if (pinned.has(key)) continue;
- const stats = statsCache!.get(key);
+ // Overrides are keyed (platform, model_id) — they only exist for
+ // catalog-managed rows, which are never endpoint-scoped — while the
+ // measured stats are per endpoint, so each relay's copy gets its own
+ // observed rank instead of one shared number (#651).
+ if (pinned.has(`${row.platform}:${row.model_id}`)) continue;
+ const stats = statsCache!.get(modelStatsKey(row.platform, row.model_id, row.endpoint_scope));
if (!stats || stats.speedSamples < SPEED_RANK_MIN_SAMPLES) continue;
const rank = observedSpeedRank(speedScore(stats.tokPerSec, stats.avgTtfbMs));
if (rank === row.speed_rank) continue;
@@ -599,7 +645,7 @@ function scoreChainEntry(
sampled: boolean,
keyCounts: Map<string, number>,
): ScoredEntry {
- const stats = statsCache?.get(`${entry.platform}:${entry.model_id}`);
+ const stats = statsCache?.get(modelStatsKey(entry.platform, entry.model_id, entry.endpoint_scope));
const successes = stats?.successes ?? 0;
const failures = stats?.failures ?? 0;
@@ -641,12 +687,16 @@ function scoreChainEntry(
* request. Priority mode is deterministic either way.
*/
function orderChain(chain: ChainRow[], strategy: RoutingStrategy, sampled = true): ChainRow[] {
+ // Tier first, always: it is the one ordering input that score must not be able
+ // to override (see ChainRow.match_tier). Zero for every chain built anywhere
+ // else, so this is a no-op outside slug-fallback resolution.
+ const tier = (e: ChainRow) => e.match_tier ?? 0;
const weights = weightsFor(strategy);
if (!weights) {
// Legacy priority mode: base priority + 429 penalty, ascending.
return chain
.map(e => ({ e, eff: e.priority + getPenalty(e.model_db_id) }))
- .sort((a, b) => a.eff - b.eff || a.e.priority - b.e.priority)
+ .sort((a, b) => tier(a.e) - tier(b.e) || a.eff - b.eff || a.e.priority - b.e.priority)
.map(x => x.e);
}
@@ -657,8 +707,9 @@ function orderChain(chain: ChainRow[], strategy: RoutingStrategy, sampled = true
return chain
.map(e => ({ e, s: scoreChainEntry(e, weights, intelMin, intelMax, sampled, keyCounts).score }))
- // Higher score first; manual priority breaks ties so the chain still matters.
- .sort((a, b) => b.s - a.s || a.e.priority - b.e.priority)
+ // Higher score first WITHIN a tier; manual priority breaks ties so the chain
+ // still matters.
+ .sort((a, b) => tier(a.e) - tier(b.e) || b.s - a.s || a.e.priority - b.e.priority)
.map(x => x.e);
}
@@ -699,7 +750,7 @@ function getActiveChain(db: Db): ChainRow[] {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM profile_models pm
JOIN models m ON m.id = pm.model_db_id AND m.enabled = 1
WHERE pm.profile_id = ?
@@ -714,7 +765,7 @@ function getActiveChain(db: Db): ChainRow[] {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM fallback_config fc
JOIN models m ON m.id = fc.model_db_id AND m.enabled = 1
ORDER BY fc.priority ASC
@@ -730,7 +781,7 @@ function getChainByProfileName(db: Db, name: string): ChainRow[] | null {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM profile_models pm
JOIN models m ON m.id = pm.model_db_id AND m.enabled = 1
WHERE pm.profile_id = ?
@@ -752,7 +803,7 @@ function getChainByGlobalSort(db: Db, globalAxis: string): ChainRow[] {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM models m
LEFT JOIN fallback_config fc ON fc.model_db_id = m.id
${profileId != null ? 'LEFT JOIN profile_models pm ON pm.profile_id = ? AND pm.model_db_id = m.id' : ''}
@@ -832,7 +883,7 @@ const KEY_SCORE_WEIGHTS = { reliability: 0.75, speed: 0.25 };
*/
function orderKeysByScore(entry: ChainRow, keys: KeyRow[]): KeyRow[] | null {
if (keys.length < 2 || !keyStatsCache) return null;
- const prefix = `${entry.platform}:${entry.model_id}:`;
+ const prefix = `${modelStatsKey(entry.platform, entry.model_id, entry.endpoint_scope)}:`;
if (!keys.some(k => keyStatsCache!.has(prefix + k.id))) return null;
return keys
@@ -894,7 +945,9 @@ function selectKeyForModel(entry: ChainRow, estimatedTokens: number, skipKeys?:
// 60s-TTL aggregate the model-level bandit uses (refresh is a no-op when
// fresh, and cheap when not). With no data at all, keep the legacy rotation.
refreshStatsCache(db);
- const rrKey = `${entry.platform}:${entry.model_id}`;
+ // Scoped so two relays offering the same model id don't share one rotation
+ // cursor over the platform's key list (#651).
+ const rrKey = modelStatsKey(entry.platform, entry.model_id, entry.endpoint_scope);
let idx = roundRobinIndex.get(rrKey) ?? 0;
const ranked = orderKeysByScore(entry, keys);
@@ -956,6 +1009,7 @@ function selectKeyForModel(entry: ChainRow, estimatedTokens: number, skipKeys?:
keyId: key.id,
platform: entry.platform,
displayName: entry.display_name,
+ endpointScope: entry.endpoint_scope ?? '',
rpdLimit: limits.rpd,
tpdLimit: limits.tpd,
release: () => releaseLease(leaseId),
@@ -1035,7 +1089,7 @@ function getModelChainRow(db: Db, modelDbId: number): ChainRow | undefined {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM models m
WHERE m.id = ? AND m.enabled = 1
`).get(modelDbId) as ChainRow | undefined;
@@ -1071,7 +1125,17 @@ export function routePinnedModel(modelDbId: number, estimatedTokens = 1000, skip
* preferred-model injection in routeRequest would unshift an off-group model and
* the pin would no longer be strict (it could answer with a different model).
*/
-export function resolveModelGroupCandidates(memberDbIds: number[]): ChainRow[] {
+export function resolveModelGroupCandidates(
+ memberDbIds: number[],
+ /**
+ * Members that were reached only through a group's auto-derived slug, not the
+ * id the client wrote (#651). They stay in the chain — resolution must never
+ * shrink — but as a strictly lower tier, so they can serve only once every
+ * literal match is exhausted. Omit it and every row is an equal candidate,
+ * which is what every other caller wants.
+ */
+ demotedDbIds?: ReadonlySet<number>,
+): ChainRow[] {
const db = getDb();
const strategy = getRoutingStrategy();
if (strategy !== 'priority') refreshStatsCache(db);
@@ -1084,7 +1148,7 @@ export function resolveModelGroupCandidates(memberDbIds: number[]): ChainRow[] {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM models m
LEFT JOIN fallback_config fc ON fc.model_db_id = m.id
WHERE m.id = ? AND m.enabled = 1
@@ -1095,7 +1159,7 @@ export function resolveModelGroupCandidates(memberDbIds: number[]): ChainRow[] {
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM models m
LEFT JOIN profile_models pm ON pm.profile_id = ? AND pm.model_db_id = m.id
LEFT JOIN fallback_config fc ON fc.model_db_id = m.id
@@ -1105,7 +1169,9 @@ export function resolveModelGroupCandidates(memberDbIds: number[]): ChainRow[] {
const rows: ChainRow[] = [];
for (const id of memberDbIds) {
const row = (activeProfileId == null ? selectMember.get(id) : selectMember.get(activeProfileId, id)) as ChainRow | undefined;
- if (row) rows.push(row);
+ if (!row) continue;
+ row.match_tier = demotedDbIds?.has(id) ? 1 : 0;
+ rows.push(row);
}
return orderChain(rows, strategy);
}
@@ -1229,9 +1295,9 @@ export function resolveFusionCandidate(modelId: string): FusionCandidate | null
// saved fusion configs that use canonical ids keep working. Exact model_id
// match above always wins first, so OFF mode and legacy configs are untouched.
if (isUnifyEnabled()) {
- const members = resolveRequestedIdToMembers(modelId, getModelGroups());
- if (members && members.length > 0) {
- const top = resolveModelGroupCandidates(members)[0];
+ const resolved = resolveRequestedIdForDispatch(modelId, getModelGroups());
+ if (resolved && resolved.memberDbIds.length > 0) {
+ const top = resolveModelGroupCandidates(resolved.memberDbIds, resolved.demotedDbIds)[0];
if (top) {
return {
modelDbId: top.model_db_id,
@@ -1275,7 +1341,7 @@ export function routeRequest(estimatedTokens = 1000, skipKeys?: Set<string>, pre
m.platform, m.model_id, m.display_name, m.intelligence_rank,
m.size_label, m.monthly_token_budget,
m.rpm_limit, m.rpd_limit, m.tpm_limit, m.tpd_limit, m.supports_vision,
- m.supports_tools, m.context_window, m.key_id
+ m.supports_tools, m.context_window, m.key_id, m.endpoint_scope
FROM models m
WHERE m.id = ? AND m.enabled = 1
`).get(preferredModelDbId) as ChainRow | undefined;
@@ -1386,7 +1452,7 @@ export function getRoutingScores(): { strategy: RoutingStrategy; weights: Routin
const scores: RoutingScore[] = chain.map(entry => {
const scored = scoreChainEntry(entry, weights, intelMin, intelMax, false, keyCounts);
- const stats = statsCache?.get(`${entry.platform}:${entry.model_id}`);
+ const stats = statsCache?.get(modelStatsKey(entry.platform, entry.model_id, entry.endpoint_scope));
return {
modelDbId: entry.model_db_id,
platform: entry.platform,