fix: add provider_key_ref under semantic.classifier

README.md

@@ -28,7 +28,7 @@ All kinds are namespaced, in `aisix.api7.ai/v1alpha1`. A `spec` is the AISIX res
 | Kind | Short name | Reference fields |
 |---|---|---|
 | `ProviderKey` | `aipk` | `api_key_secret_ref: {name, key}`: the upstream credential |
-| `Model` | `aimodel` | `provider_key_ref: {name}`: a ProviderKey's `metadata.name` (direct models only) |
+| `Model` | `aimodel` | `provider_key_ref: {name}`: a ProviderKey's `metadata.name`, on direct models and under a semantic router's `semantic.classifier` |
 | `APIKey` | `aikey` | `key_secret_ref: {name, key}`: the caller's plaintext key; only its SHA-256 is written |
 
 Secret refs may name any Secret in the namespace except the controller's own `aisix-resources`. A `provider_key_ref` must name a ProviderKey that is served, and resolves to the `display_name` that ProviderKey is actually served under. A resource already served under a `display_name` keeps it, so another resource claiming it is refused; when none is served under it, the oldest wins.

api/v1alpha1/kind.go

@@ -105,3 +105,8 @@ const (
 	// HashAnnotation carries the served resources-file hash.
 	HashAnnotation = "aisix.api7.ai/resources-hash"
 )
+
+// ProviderKeyRefPaths are the objects in a Model spec that hold a
+// ProviderKeyRef: the root, for direct models, and a semantic router's
+// classifier.
+var ProviderKeyRefPaths = [][]string{nil, {"semantic", "classifier"}}

config/crd/models.aisix.api7.ai.yaml

@@ -303,7 +303,8 @@ spec:
               provider_key_ref:
                 description: ProviderKey, in the same namespace, this model authenticates
                   with. Direct models need it; routing, ensemble and semantic models
-                  leave it unset.
+                  leave it unset. A semantic router's classifier sets its own under
+                  `semantic.classifier`.
                 properties:
                   name:
                     description: ProviderKey `metadata.name`.
@@ -517,6 +518,18 @@ spec:
                           out, or returns an answer that names no route. Same values
                           as `on_embedding_failure`.
                         x-kubernetes-preserve-unknown-fields: true
+                      provider_key_ref:
+                        description: ProviderKey, in the same namespace, that authenticates
+                          the classifier's decision calls. Its `provider` must be
+                          `typesafe`.
+                        properties:
+                          name:
+                            description: ProviderKey `metadata.name`.
+                            minLength: 1
+                            type: string
+                        required:
+                        - name
+                        type: object
                       timeout_ms:
                         description: Deadline for the decision call, in milliseconds.
                         minimum: 1
@@ -529,6 +542,7 @@ spec:
                         type: string
                     required:
                     - type
+                    - provider_key_ref
                     type: object
                   default:
                     description: Direct model alias used when no route clears its

internal/render/assemble.go

@@ -187,9 +187,9 @@ type item struct {
 	entry  Entry
 	// identity the entry is served under.
 	identity string
-	// providerRef is the metadata.name of the ProviderKey the entry uses.
-	providerRef string
-	reason      string
+	// providerRefs are the ProviderKeys the entry uses.
+	providerRefs []ProviderRef
+	reason       string
 }
 
 // assembly is the working state of one Assemble call.
@@ -206,28 +206,30 @@ func (a *assembly) fallback(it *item, reason string) {
 	it.reason = reason
 	e, id, ok := a.served.get(it.source)
 	if !ok {
-		it.state, it.entry, it.identity, it.providerRef = Rejected, nil, "", ""
+		it.state, it.entry, it.identity, it.providerRefs = Rejected, nil, "", nil
 		return
 	}
-	it.state, it.entry, it.identity, it.providerRef = Retained, e, id, ""
+	it.state, it.entry, it.identity, it.providerRefs = Retained, e, id, nil
 	if it.source.Kind != v1alpha1.KindModel {
 		return
 	}
-	name, ok := e[providerKeyField].(string)
-	if !ok {
-		return
-	}
-	owner, ok := a.served.providers[unescapeDollars(name)]
-	if !ok {
-		a.drop(it, fmt.Sprintf("no ProviderKey owns %s %q", providerKeyField, unescapeDollars(name)))
-		return
+	for _, path := range v1alpha1.ProviderKeyRefPaths {
+		name, ok := objectAt(e, path)[providerKeyField].(string)
+		if !ok {
+			continue
+		}
+		owner, ok := a.served.providers[unescapeDollars(name)]
+		if !ok {
+			a.drop(it, fmt.Sprintf("no ProviderKey owns %s %q", fieldAt(path, providerKeyField), unescapeDollars(name)))
+			return
+		}
+		it.providerRefs = append(it.providerRefs, ProviderRef{Path: path, Name: owner})
 	}
-	it.providerRef = owner
 }
 
 // drop rejects a Retained item.
 func (a *assembly) drop(it *item, reason string) {
-	it.state, it.entry, it.identity, it.providerRef = Rejected, nil, "", ""
+	it.state, it.entry, it.identity, it.providerRefs = Rejected, nil, "", nil
 	it.reason += "; the previously served version is no longer valid either: " + reason
 }
 
@@ -263,23 +265,16 @@ func (a *assembly) claim() bool {
 	return changed
 }
 
-// resolve points each Model at the display_name its ProviderKey is served
-// under now.
+// resolve points each Model at the display_names its ProviderKeys are
+// served under now.
 func (a *assembly) resolve() bool {
 	changed := false
 	for _, it := range a.items {
-		if it.state == Rejected || it.providerRef == "" {
+		if it.state == Rejected {
 			continue
 		}
-		var problem string
-		p := a.providers[it.providerRef]
-		switch {
-		case p == nil:
-			problem = fmt.Sprintf("%s names ProviderKey %q, which does not exist", v1alpha1.ProviderKeyRef, it.providerRef)
-		case p.state == Rejected:
-			problem = fmt.Sprintf("%s names ProviderKey %q, which is not served: %s", v1alpha1.ProviderKeyRef, it.providerRef, p.reason)
-		default:
-			it.setProviderKey(p.identity)
+		problem := a.bind(it)
+		if problem == "" {
 			continue
 		}
 		if it.state == Applied {
@@ -292,13 +287,29 @@ func (a *assembly) resolve() bool {
 	return changed
 }
 
+// bind writes each ref's served display_name into the entry, or says why
+// one has none.
+func (a *assembly) bind(it *item) string {
+	for _, r := range it.providerRefs {
+		p := a.providers[r.Name]
+		switch {
+		case p == nil:
+			return fmt.Sprintf("%s names ProviderKey %q, which does not exist", r.Field(), r.Name)
+		case p.state == Rejected:
+			return fmt.Sprintf("%s names ProviderKey %q, which is not served: %s", r.Field(), r.Name, p.reason)
+		}
+		it.setProviderKey(r.Path, p.identity)
+	}
+	return ""
+}
+
 // setProviderKey copies the entry, since a Retained one is shared with Served.
-func (it *item) setProviderKey(identity string) {
-	e := make(Entry, len(it.entry)+1)
-	for k, v := range it.entry {
-		e[k] = v
+func (it *item) setProviderKey(path []string, identity string) {
+	e, m := clonePath(it.entry, path)
+	if m == nil {
+		return
 	}
-	e[providerKeyField] = EscapeDollars(identity)
+	m[providerKeyField] = EscapeDollars(identity)
 	it.entry = e
 }
 
@@ -321,7 +332,7 @@ func Assemble(ctx context.Context, rendered []Rendered, served Served, v validat
 	items := make([]*item, len(rendered))
 	a := &assembly{items: items, served: served, providers: map[string]*item{}}
 	for i, r := range rendered {
-		it := &item{source: r.Source, state: Applied, entry: r.Entry, identity: r.Source.Identity(), providerRef: r.ProviderRef}
+		it := &item{source: r.Source, state: Applied, entry: r.Entry, identity: r.Source.Identity(), providerRefs: r.ProviderRefs}
 		if r.Err != "" {
 			a.fallback(it, r.Err)
 		}

internal/render/assemble_test.go

@@ -41,8 +41,10 @@ func (f *fakeValidator) Validate(_ context.Context, doc []byte) ([]validate.Load
 	for _, k := range v1alpha1.Kinds {
 		for i, e := range list(root, k.Collection()) {
 			scope := fmt.Sprintf("%s[%d] (%q)", k.Collection(), i, e[v1alpha1.IdentityField])
-			if name, ok := e["provider_key"].(string); ok && !providers[name] {
-				errs = append(errs, validate.LoadError{Scope: scope, Message: fmt.Sprintf("`provider_key` references unknown provider key %q", name)})
+			for _, path := range v1alpha1.ProviderKeyRefPaths {
+				if name, ok := objectAt(e, path)["provider_key"].(string); ok && !providers[name] {
+					errs = append(errs, validate.LoadError{Scope: scope, Message: fmt.Sprintf("`%s` references unknown provider key %q", fieldAt(path, "provider_key"), name)})
+				}
 			}
 			if f.reject != nil {
 				if msg := f.reject(k, e); msg != "" {
@@ -575,6 +577,77 @@ func TestModelIsRejectedWithItsProviderKey(t *testing.T) {
 	}
 }
 
+// typesafe is a ProviderKey for a classifier's decision calls.
+func typesafe(name, display string) Source {
+	return src(v1alpha1.KindProviderKey, name, map[string]any{
+		"provider": "typesafe", v1alpha1.IdentityField: display,
+		v1alpha1.APIKeySecretRef: ref("creds", "caller"),
+	})
+}
+
+// router is a semantic router whose classifier uses providerRef.
+func router(name, providerRef string) Source {
+	return src(v1alpha1.KindModel, name, map[string]any{
+		"semantic": map[string]any{
+			"classifier": map[string]any{
+				"type":                  "jev",
+				v1alpha1.ProviderKeyRef: map[string]any{"name": providerRef},
+			},
+			"default": "chat",
+			"routes": []any{map[string]any{
+				"name": "billing", "target": "chat", "description": "billing questions",
+			}},
+		},
+	})
+}
+
+// wantClassifier checks which provider key a router's classifier is served on.
+func wantClassifier(t *testing.T, o Outcome, model, providerKey string) {
+	t.Helper()
+	m, ok := entries(t, o, "models")[model]
+	if !ok {
+		t.Fatalf("model %s is not served:\n%s", model, o.Document)
+	}
+	if got := objectAt(m, v1alpha1.ProviderKeyRefPaths[1])["provider_key"]; got != providerKey {
+		t.Errorf("model %s: classifier provider_key = %v, want %s", model, got, providerKey)
+	}
+}
+
+func TestClassifierResolvesToTheProviderDisplayName(t *testing.T) {
+	v := gatewayValidator(t, &fakeValidator{})
+	out := assemble(t, v, []Source{provider(), typesafe("ts", "TypeSafe Key"), model("chat", "mock"), router("router", "ts")}, nil)
+	wantState(t, out, v1alpha1.KindModel, "router", Applied, "")
+	wantClassifier(t, out, "router", "TypeSafe Key")
+}
+
+func TestClassifierNamingAMissingProviderKeyIsRejected(t *testing.T) {
+	v := gatewayValidator(t, &fakeValidator{})
+	out := assemble(t, v, []Source{provider(), model("chat", "mock"), router("router", "ghost")}, nil)
+	wantState(t, out, v1alpha1.KindModel, "router", Rejected, `semantic.classifier.provider_key_ref names ProviderKey "ghost", which does not exist`)
+	wantState(t, out, v1alpha1.KindModel, "chat", Applied, "")
+}
+
+func TestRetainedClassifierFollowsItsProviderKeyRename(t *testing.T) {
+	v := gatewayValidator(t, &fakeValidator{reject: rejectUnknownField})
+	first := assemble(t, v, []Source{provider(), typesafe("ts", "A"), model("chat", "mock"), router("router", "ts")}, nil)
+	out := assemble(t, v, []Source{provider(), typesafe("ts", "B"), model("chat", "mock"), invalid(router("router", "ts"))}, &first)
+	wantState(t, out, v1alpha1.KindProviderKey, "ts", Applied, "")
+	wantState(t, out, v1alpha1.KindModel, "router", Retained, "no_such_field")
+	wantClassifier(t, out, "router", "B")
+}
+
+func TestRetainedClassifierIsRejectedWithItsProviderKey(t *testing.T) {
+	v := &fakeValidator{}
+	first := assemble(t, v, []Source{provider(), typesafe("ts", "A"), model("chat", "mock"), router("router", "ts")}, nil)
+	// ts is deleted, and the router's new spec names it.
+	out := assemble(t, v, []Source{provider(), model("chat", "mock"), router("router", "ts")}, &first)
+	wantState(t, out, v1alpha1.KindModel, "router", Rejected, `semantic.classifier.provider_key_ref names ProviderKey "ts", which does not exist`)
+	wantState(t, out, v1alpha1.KindModel, "router", Rejected, "the previously served version is no longer valid either")
+	if _, ok := entries(t, out, "models")["router"]; ok {
+		t.Errorf("router is still served:\n%s", out.Document)
+	}
+}
+
 func TestDollarsInAProviderDisplayNameStayEscaped(t *testing.T) {
 	v := gatewayValidator(t, &fakeValidator{reject: rejectUnknownField})
 	first := assemble(t, v, []Source{namedProvider("p", "a$b", "openai", 0), model("m", "p")}, nil)