feat(api): add /v1/detokenize endpoint (#9620)

* feat(api): add /v1/detokenize endpoint

Closes #1649.

Mirror of the existing /v1/tokenize path, requested by @benniekiss in
the issue thread for "complete API workflow" use cases that need to
turn token IDs back into text without local processing.

- Add Detokenize gRPC RPC with DetokenizeRequest{tokens} /
  DetokenizeResponse{content} messages.
- Implement in the llama.cpp backend using common_token_to_piece, the
  same primitive TokenizeString already uses internally.
- Other backends inherit the default Unimplemented from base.Base, in
  line with how Detect, Rerank, etc. are gated per-backend.
- Wire up the Go gRPC interface, server, client, and in-process embed
  wrapper alongside their TokenizeString counterparts.
- Add the schema types, ModelDetokenize wrapper, HTTP handler, route
  registration, RouteFeatureRegistry entry (gated by FeatureTokenize so
  no new feature flag is needed), and the discovery map entry under
  ai_functions.
- Regenerated swagger reflects the new endpoint and types.
- Update authentication.md to list /v1/detokenize alongside /v1/tokenize.

Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Adira Denis Muhando <dennisadira@gmail.com>

* test(e2e): add mock backend tests for /v1/detokenize

Add Detokenize to the mock gRPC backend and wire up two e2e tests in
the MockBackend suite: one that posts known token IDs and asserts a
non-empty content response, and a round-trip that tokenizes first then
detokenizes the returned IDs.

Addresses reviewer feedback on #9620.

Assisted-by: Claude:claude-sonnet-4-6
Signed-off-by: Adira Denis Muhando <dennisadira@gmail.com>

* fix(kokoros): implement detokenize in the Rust backend service

The Detokenize RPC added in this PR grows the tonic-generated Backend
trait. Unlike the other languages there is nothing to inherit a default
from — Rust trait impls must list every method — so
backend/rust/kokoros failed to compile:

  error[E0046]: not all trait items implemented, missing: `detokenize`
    --> src/service.rs:72:1
  72 | impl Backend for KokorosService {

Go backends pick up the Unimplemented default from base.Base, and the
generated C++/Python servicer bases default to UNIMPLEMENTED, which is
why the Rust backend was the only one that broke. kokoros is the sole
Rust crate in the tree, so this is the full extent of the fallout.

Return Status::unimplemented("Not supported"), matching how this same
file already gates tokenize_string and ~20 other unsupported RPCs.

Fixes the tests-kokoros and backend-jobs-singlearch-4 (-cpu-kokoros)
failures on the previous head.

Assisted-by: Claude:claude-opus-5 cargo
Signed-off-by: Adira Denis Muhando <dennisadira@gmail.com>

---------

Signed-off-by: Adira Denis Muhando <dennisadira@gmail.com>
Co-authored-by: localai-org-maint-bot <bot-opensource@localaisrl.com>

Author: Dennisadira

backend/backend.proto

@@ -35,6 +35,7 @@ service Backend {
   rpc TTSStream(TTSRequest) returns (stream Reply) {}
   rpc SoundGeneration(SoundGenerationRequest) returns (Result) {}
   rpc TokenizeString(PredictOptions) returns (TokenizationResponse) {}
+  rpc Detokenize(DetokenizeRequest) returns (DetokenizeResponse) {}
   rpc Status(HealthMessage) returns (StatusResponse) {}
   rpc Detect(DetectOptions) returns (DetectResponse) {}
   // SoundDetection runs an audio-tagging / sound-event-classification model
@@ -796,6 +797,14 @@ message TokenizationResponse {
   repeated int32 tokens = 2;
 }
 
+message DetokenizeRequest {
+  repeated int32 tokens = 1;
+}
+
+message DetokenizeResponse {
+  string content = 1;
+}
+
 message MemoryUsageData {
   uint64 total = 1;
   map<string, uint64> breakdown = 2;

backend/cpp/llama-cpp/grpc-server.cpp

@@ -3279,6 +3279,21 @@ class BackendServiceImpl final : public backend::Backend::Service {
         return grpc::Status::OK;
     }
 
+    grpc::Status Detokenize(ServerContext* context, const backend::DetokenizeRequest* request, backend::DetokenizeResponse* response) override {
+        auto auth = checkAuth(context);
+        if (!auth.ok()) return auth;
+        if (params_base.model.path.empty()) {
+            return grpc::Status(grpc::StatusCode::FAILED_PRECONDITION, "Model not loaded");
+        }
+
+        std::string content;
+        for (const auto token : request->tokens()) {
+            content.append(common_token_to_piece(ctx_server.get_llama_context(), token));
+        }
+        response->set_content(content);
+        return grpc::Status::OK;
+    }
+
     grpc::Status GetMetrics(ServerContext* /*context*/, const backend::MetricsRequest* /*request*/, backend::MetricsResponse* response) override {
 
 

backend/rust/kokoros/src/service.rs

@@ -415,6 +415,13 @@ impl Backend for KokorosService {
         Err(Status::unimplemented("Not supported"))
     }
 
+    async fn detokenize(
+        &self,
+        _: Request<backend::DetokenizeRequest>,
+    ) -> Result<Response<backend::DetokenizeResponse>, Status> {
+        Err(Status::unimplemented("Not supported"))
+    }
+
     async fn detect(
         &self,
         _: Request<backend::DetectOptions>,

core/backend/detokenize.go

@@ -0,0 +1,67 @@
+package backend
+
+import (
+	"time"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/core/trace"
+	"github.com/mudler/LocalAI/pkg/grpc"
+	pb "github.com/mudler/LocalAI/pkg/grpc/proto"
+	"github.com/mudler/LocalAI/pkg/model"
+)
+
+func ModelDetokenize(tokens []int32, loader *model.ModelLoader, modelConfig config.ModelConfig, appConfig *config.ApplicationConfig) (schema.DetokenizeResponse, error) {
+
+	var inferenceModel grpc.Backend
+	var err error
+
+	opts := ModelOptions(modelConfig, appConfig)
+	inferenceModel, err = loader.Load(opts...)
+	if err != nil {
+		recordModelLoadFailure(appConfig, modelConfig.Name, modelConfig.Backend, err, nil)
+		return schema.DetokenizeResponse{}, err
+	}
+
+	var startTime time.Time
+	if appConfig.EnableTracing {
+		trace.InitBackendTracingIfEnabled(appConfig.TracingMaxItems, appConfig.TracingMaxBodyBytes)
+		startTime = time.Now()
+	}
+
+	resp, err := inferenceModel.Detokenize(appConfig.Context, &pb.DetokenizeRequest{Tokens: tokens})
+
+	if appConfig.EnableTracing {
+		errStr := ""
+		if err != nil {
+			errStr = err.Error()
+		}
+
+		content := ""
+		if resp != nil {
+			content = resp.Content
+		}
+
+		trace.RecordBackendTrace(trace.BackendTrace{
+			Timestamp: startTime,
+			Duration:  time.Since(startTime),
+			Type:      trace.BackendTraceTokenize,
+			ModelName: modelConfig.Name,
+			Backend:   modelConfig.Backend,
+			Summary:   trace.TruncateString(content, 200),
+			Error:     errStr,
+			Data: map[string]any{
+				"token_count": len(tokens),
+				"output_text": trace.TruncateString(content, 1000),
+			},
+		})
+	}
+
+	if err != nil {
+		return schema.DetokenizeResponse{}, err
+	}
+
+	return schema.DetokenizeResponse{
+		Content: resp.Content,
+	}, nil
+}

core/http/auth/features.go

@@ -111,6 +111,7 @@ var RouteFeatureRegistry = []RouteFeature{
 
 	// Tokenize
 	{"POST", "/v1/tokenize", FeatureTokenize},
+	{"POST", "/v1/detokenize", FeatureTokenize},
 
 	// Rerank
 	{"POST", "/v1/rerank", FeatureRerank},

core/http/endpoints/localai/detokenize.go

@@ -0,0 +1,36 @@
+package localai
+
+import (
+	"github.com/labstack/echo/v4"
+	"github.com/mudler/LocalAI/core/backend"
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/mudler/LocalAI/core/http/middleware"
+	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/pkg/model"
+)
+
+// DetokenizeEndpoint exposes a REST API to convert token IDs back to text.
+// @Summary Detokenize the input.
+// @Tags tokenize
+// @Param request body schema.DetokenizeRequest true "Request"
+// @Success 200 {object} schema.DetokenizeResponse "Response"
+// @Router /v1/detokenize [post]
+func DetokenizeEndpoint(cl *config.ModelConfigLoader, ml *model.ModelLoader, appConfig *config.ApplicationConfig) echo.HandlerFunc {
+	return func(c echo.Context) error {
+		input, ok := c.Get(middleware.CONTEXT_LOCALS_KEY_LOCALAI_REQUEST).(*schema.DetokenizeRequest)
+		if !ok || input.Model == "" {
+			return echo.ErrBadRequest
+		}
+
+		cfg, ok := c.Get(middleware.CONTEXT_LOCALS_KEY_MODEL_CONFIG).(*config.ModelConfig)
+		if !ok || cfg == nil {
+			return echo.ErrBadRequest
+		}
+
+		resp, err := backend.ModelDetokenize(input.Tokens, ml, *cfg, appConfig)
+		if err != nil {
+			return err
+		}
+		return c.JSON(200, resp)
+	}
+}

core/http/routes/localai.go

@@ -348,6 +348,7 @@ func RegisterLocalAIRoutes(router *echo.Echo,
 					"3d_generation":  "/3d/generations",
 					"detection":      "/v1/detection",
 					"tokenize":       "/v1/tokenize",
+					"detokenize":     "/v1/detokenize",
 				},
 				"monitoring": monitoringRoutes,
 				"mcp": map[string]string{
@@ -417,6 +418,12 @@ func RegisterLocalAIRoutes(router *echo.Echo,
 		requestExtractor.BuildFilteredFirstAvailableDefaultModel(config.BuildUsecaseFilterFn(config.FLAG_TOKENIZE)),
 		requestExtractor.SetModelAndConfig(func() schema.LocalAIRequest { return new(schema.TokenizeRequest) }))
 
+	detokenizeHandler := localai.DetokenizeEndpoint(cl, ml, appConfig)
+	router.POST("/v1/detokenize",
+		detokenizeHandler,
+		requestExtractor.BuildFilteredFirstAvailableDefaultModel(config.BuildUsecaseFilterFn(config.FLAG_TOKENIZE)),
+		requestExtractor.SetModelAndConfig(func() schema.LocalAIRequest { return new(schema.DetokenizeRequest) }))
+
 	// MCP endpoint - supports both streaming and non-streaming modes
 	// Note: streaming mode is NOT compatible with the OpenAI apis. We have a set which streams more states.
 	if evaluator != nil && !appConfig.DisableMCP {

core/schema/tokenize.go

@@ -8,3 +8,12 @@ type TokenizeRequest struct {
 type TokenizeResponse struct {
 	Tokens []int32 `json:"tokens"` // token IDs
 }
+
+type DetokenizeRequest struct {
+	BasicModelRequest
+	Tokens []int32 `json:"tokens"` // token IDs to convert back to text
+}
+
+type DetokenizeResponse struct {
+	Content string `json:"content"` // detokenized text
+}

core/services/nodes/health_mock_test.go

@@ -202,6 +202,9 @@ func (c *fakeBackendClient) AudioTranscriptionStream(_ context.Context, _ *pb.Tr
 func (c *fakeBackendClient) TokenizeString(_ context.Context, _ *pb.PredictOptions, _ ...ggrpc.CallOption) (*pb.TokenizationResponse, error) {
 	return nil, nil
 }
+func (c *fakeBackendClient) Detokenize(_ context.Context, _ *pb.DetokenizeRequest, _ ...ggrpc.CallOption) (*pb.DetokenizeResponse, error) {
+	return nil, nil
+}
 func (c *fakeBackendClient) Status(_ context.Context) (*pb.StatusResponse, error) {
 	return nil, nil
 }

core/services/nodes/inflight_test.go

@@ -146,6 +146,10 @@ func (f *fakeGRPCBackend) TokenizeString(_ context.Context, _ *pb.PredictOptions
 	return &pb.TokenizationResponse{}, nil
 }
 
+func (f *fakeGRPCBackend) Detokenize(_ context.Context, _ *pb.DetokenizeRequest, _ ...ggrpc.CallOption) (*pb.DetokenizeResponse, error) {
+	return &pb.DetokenizeResponse{}, nil
+}
+
 func (f *fakeGRPCBackend) Status(_ context.Context) (*pb.StatusResponse, error) {
 	return &pb.StatusResponse{}, nil
 }