feat(handlers): suggest closest models and point to /v1/models on unknown-provider error

docker-compose.cluster.yml

@@ -1,20 +1,17 @@
 services:
   cli-proxy-api:
-    image: ${CLI_PROXY_IMAGE:-eceasy/cli-proxy-api:latest}
-    pull_policy: always
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        VERSION: ${VERSION:-dev}
-        COMMIT: ${COMMIT:-none}
-        BUILD_DATE: ${BUILD_DATE:-unknown}
+    image: golang:1.26-bookworm
     container_name: cli-proxy-api-cluster
+    working_dir: /CLIProxyAPI
     environment:
       HOME_JWT: ${HOME_JWT:-}
+      TZ: Asia/Shanghai
     ports:
       - "8317:8317"
     volumes:
+      - .:/CLIProxyAPI
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
       - ./home:/root/.cli-proxy-api
       - ./logs:/CLIProxyAPI/logs
     command: >
@@ -24,6 +21,10 @@ services:
           exit 1
         fi
 
-        exec ./CLIProxyAPI -home-jwt "$$HOME_JWT"
+        cd /CLIProxyAPI && exec go run -buildvcs=false ./cmd/server/ -home-jwt "$$HOME_JWT"
       '
-    restart: unless-stopped
+    restart: unless-stopped
+
+volumes:
+  go-mod-cache:
+  go-build-cache:

docker-compose.dev.yml

@@ -0,0 +1,29 @@
+services:
+  cli-proxy-api-dev:
+    image: golang:1.26-bookworm
+    container_name: cli-proxy-api-dev
+    working_dir: /CLIProxyAPI
+    environment:
+      TZ: Asia/Shanghai
+      DEPLOY: ${DEPLOY:-}
+    ports:
+      - "8317:8317"
+      - "8085:8085"
+      - "1455:1455"
+      - "54545:54545"
+      - "51121:51121"
+      - "11451:11451"
+    volumes:
+      - .:/CLIProxyAPI
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
+      - ${CLI_PROXY_CONFIG_PATH:-./config.yaml}:/CLIProxyAPI/config.yaml
+      - ${CLI_PROXY_AUTH_PATH:-./auths}:/root/.cli-proxy-api
+      - ${CLI_PROXY_LOG_PATH:-./logs}:/CLIProxyAPI/logs
+    command: >
+      bash -c "cd /CLIProxyAPI && go run -buildvcs=false ./cmd/server/"
+    restart: unless-stopped
+
+volumes:
+  go-mod-cache:
+  go-build-cache:

docker-compose.yml

@@ -1,19 +1,11 @@
 services:
   cli-proxy-api:
-    image: ${CLI_PROXY_IMAGE:-eceasy/cli-proxy-api:latest}
-    pull_policy: always
-    build:
-      context: .
-      dockerfile: Dockerfile
-      args:
-        VERSION: ${VERSION:-dev}
-        COMMIT: ${COMMIT:-none}
-        BUILD_DATE: ${BUILD_DATE:-unknown}
+    image: golang:1.26-bookworm
     container_name: cli-proxy-api
-    # env_file:
-    #   - .env
+    working_dir: /CLIProxyAPI
     environment:
       DEPLOY: ${DEPLOY:-}
+      TZ: Asia/Shanghai
     ports:
       - "8317:8317"
       - "8085:8085"
@@ -22,7 +14,16 @@ services:
       - "51121:51121"
       - "11451:11451"
     volumes:
+      - .:/CLIProxyAPI
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
       - ${CLI_PROXY_CONFIG_PATH:-./config.yaml}:/CLIProxyAPI/config.yaml
       - ${CLI_PROXY_AUTH_PATH:-./auths}:/root/.cli-proxy-api
       - ${CLI_PROXY_LOG_PATH:-./logs}:/CLIProxyAPI/logs
+    command: >
+      bash -c "cd /CLIProxyAPI && go run -buildvcs=false ./cmd/server/"
     restart: unless-stopped
+
+volumes:
+  go-mod-cache:
+  go-build-cache:

internal/util/provider.go

@@ -5,6 +5,7 @@ package util
 
 import (
 	"net/url"
+	"sort"
 	"strings"
 
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/config"
@@ -286,3 +287,113 @@ func shouldMaskQueryParam(key string) bool {
 	}
 	return false
 }
+
+// suggestMaxDistance is the maximum normalized Levenshtein distance (0..1) for a
+// registered model ID to be offered as a "did you mean" suggestion. A wrong
+// suggestion is worse than none, so this is kept strict.
+const suggestMaxDistance = 0.34
+
+// SuggestClosestModels returns up to limit registered model IDs that are close
+// to modelName, to help users recover from an "unknown provider" error caused by
+// a typo, a wrong alias, or a stale thinking suffix.
+//
+// modelName should already be suffix-stripped by the caller (the base model
+// name). Registered IDs are matched after stripping any "provider/" prefix.
+// Only matches within a normalized Levenshtein distance are returned.
+//
+// This runs only on the error path and GetAvailableModels is cached, so there
+// is no hot-path impact.
+func SuggestClosestModels(modelName string, limit int) []string {
+	modelName = strings.ToLower(strings.TrimSpace(modelName))
+	if modelName == "" || limit <= 0 {
+		return nil
+	}
+
+	type candidate struct {
+		id   string
+		dist int
+	}
+	var cands []candidate
+	for _, m := range registry.GetGlobalRegistry().GetAvailableModels("") {
+		id, _ := m["id"].(string)
+		if id == "" {
+			continue
+		}
+		base := stripProviderPrefix(id)
+		d := levenshtein(modelName, strings.ToLower(base))
+		maxLen := len(modelName)
+		if len(base) > maxLen {
+			maxLen = len(base)
+		}
+		if maxLen == 0 {
+			continue
+		}
+		if float64(d)/float64(maxLen) <= suggestMaxDistance {
+			cands = append(cands, candidate{id: id, dist: d})
+		}
+	}
+
+	sort.Slice(cands, func(i, j int) bool {
+		if cands[i].dist != cands[j].dist {
+			return cands[i].dist < cands[j].dist
+		}
+		return cands[i].id < cands[j].id
+	})
+
+	out := make([]string, 0, limit)
+	for i := 0; i < limit && i < len(cands); i++ {
+		out = append(out, cands[i].id)
+	}
+	return out
+}
+
+// stripProviderPrefix returns the trailing segment after the last "/",
+// mirroring handlers.routeModelBaseName without creating a cross-package
+// dependency (internal/util must not import sdk/api/handlers).
+func stripProviderPrefix(model string) string {
+	model = strings.TrimSpace(model)
+	if idx := strings.LastIndex(model, "/"); idx >= 0 && idx < len(model)-1 {
+		return strings.TrimSpace(model[idx+1:])
+	}
+	return model
+}
+
+// levenshtein computes the edit distance between two strings using a standard
+// two-row dynamic programming algorithm. Pure stdlib, no external dependency.
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	la, lb := len(ra), len(rb)
+	if la == 0 {
+		return lb
+	}
+	if lb == 0 {
+		return la
+	}
+
+	prev := make([]int, lb+1)
+	curr := make([]int, lb+1)
+	for j := 0; j <= lb; j++ {
+		prev[j] = j
+	}
+	for i := 1; i <= la; i++ {
+		curr[0] = i
+		for j := 1; j <= lb; j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			ins := curr[j-1] + 1
+			del := prev[j] + 1
+			sub := prev[j-1] + cost
+			curr[j] = ins
+			if del < curr[j] {
+				curr[j] = del
+			}
+			if sub < curr[j] {
+				curr[j] = sub
+			}
+		}
+		prev, curr = curr, prev
+	}
+	return prev[lb]
+}

sdk/api/handlers/handlers.go

@@ -1495,7 +1495,11 @@ func (h *BaseAPIHandler) getRequestDetailsWithOptions(modelName string, allowIma
 	}
 
 	if len(providers) == 0 {
-		return nil, "", &interfaces.ErrorMessage{StatusCode: http.StatusBadGateway, Error: fmt.Errorf("unknown provider for model %s", modelName)}
+		msg := fmt.Sprintf("unknown provider for model %s; check available models via GET /v1/models", modelName)
+		if sugg := util.SuggestClosestModels(baseModel, 3); len(sugg) > 0 {
+			msg = fmt.Sprintf("unknown provider for model %s; did you mean %s? check available models via GET /v1/models", modelName, strings.Join(sugg, ", "))
+		}
+		return nil, "", &interfaces.ErrorMessage{StatusCode: http.StatusBadGateway, Error: fmt.Errorf("%s", msg)}
 	}
 
 	// The thinking suffix is preserved in the model name itself, so no

sdk/api/handlers/handlers_request_details_test.go

@@ -137,3 +137,40 @@ func TestGetRequestDetails_ImageModelReturns503(t *testing.T) {
 		t.Fatalf("unexpected error message: %q", msg)
 	}
 }
+
+func TestGetRequestDetails_UnknownModelSuggestsClosest(t *testing.T) {
+	modelRegistry := registry.GetGlobalRegistry()
+	now := time.Now().Unix()
+
+	modelRegistry.RegisterClient("test-suggest-closest", "gemini", []*registry.ModelInfo{
+		{ID: "gemini-2.5-pro", Created: now + 30},
+		{ID: "gemini-2.5-flash", Created: now + 25},
+	})
+	t.Cleanup(func() { modelRegistry.UnregisterClient("test-suggest-closest") })
+
+	handler := NewBaseAPIHandlers(&sdkconfig.SDKConfig{}, coreauth.NewManager(nil, nil, nil))
+
+	// Near-miss of a registered model: the error should suggest the close match.
+	_, _, errMsg := handler.getRequestDetails("gemini-2.5-proo")
+	if errMsg == nil || errMsg.Error == nil {
+		t.Fatalf("expected unknown-provider error for gemini-2.5-proo, got: %v", errMsg)
+	}
+	msg := errMsg.Error.Error()
+	if !strings.Contains(msg, "did you mean gemini-2.5-pro") {
+		t.Fatalf("expected a closest-match suggestion in error, got %q", msg)
+	}
+
+	// Totally unknown model: no close match, so the error should point to /v1/models
+	// instead of offering a misleading suggestion.
+	_, _, errMsg2 := handler.getRequestDetails("totally-bogus-xyz-12345")
+	if errMsg2 == nil || errMsg2.Error == nil {
+		t.Fatalf("expected unknown-provider error for totally-bogus-xyz-12345, got: %v", errMsg2)
+	}
+	msg2 := errMsg2.Error.Error()
+	if !strings.Contains(msg2, "/v1/models") {
+		t.Fatalf("expected /v1/models hint in error, got %q", msg2)
+	}
+	if strings.Contains(msg2, "did you mean") {
+		t.Fatalf("did not expect a suggestion for a bogus model, got %q", msg2)
+	}
+}