feat(api): add /v1/detokenize endpoint

backend/backend.proto

@@ -34,6 +34,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
@@ -781,6 +782,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

@@ -3251,6 +3251,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

@@ -408,6 +408,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

@@ -107,6 +107,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

@@ -335,6 +335,7 @@ func RegisterLocalAIRoutes(router *echo.Echo,
 					"video":          "/video",
 					"detection":      "/v1/detection",
 					"tokenize":       "/v1/tokenize",
+					"detokenize":     "/v1/detokenize",
 				},
 				"monitoring": monitoringRoutes,
 				"mcp": map[string]string{
@@ -404,6 +405,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

@@ -199,6 +199,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

@@ -142,6 +142,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
 }

docs/content/features/authentication.md

@@ -179,7 +179,7 @@ When authentication is enabled, the following endpoints require admin role:
 **User-Accessible Endpoints (all authenticated users):**
 - `POST /v1/chat/completions`, `POST /v1/embeddings`, `POST /v1/completions`
 - `POST /v1/images/generations`, `POST /v1/audio/*`, `POST /tts`, `POST /vad`, `POST /video`
-- `GET /v1/models`, `POST /v1/tokenize`, `POST /v1/detection`
+- `GET /v1/models`, `POST /v1/tokenize`, `POST /v1/detokenize`, `POST /v1/detection`
 - `POST /v1/mcp/chat/completions`, `POST /v1/messages`, `POST /v1/responses`
 - `POST /stores/*`, `GET /api/cors-proxy`
 - `GET /version`, `GET /api/features`, `GET /swagger/*`, `GET /metrics`

pkg/grpc/backend.go

@@ -105,6 +105,7 @@ type ControlBackend interface {
 	HealthCheck(ctx context.Context) (bool, error)
 	LoadModel(ctx context.Context, in *pb.ModelOptions, opts ...grpc.CallOption) (*pb.Result, error)
 	TokenizeString(ctx context.Context, in *pb.PredictOptions, opts ...grpc.CallOption) (*pb.TokenizationResponse, error)
+	Detokenize(ctx context.Context, in *pb.DetokenizeRequest, opts ...grpc.CallOption) (*pb.DetokenizeResponse, error)
 	Status(ctx context.Context) (*pb.StatusResponse, error)
 
 	StoresSet(ctx context.Context, in *pb.StoresSetOptions, opts ...grpc.CallOption) (*pb.Result, error)

pkg/grpc/base/base.go

@@ -119,6 +119,10 @@ func (llm *Base) TokenizeString(opts *pb.PredictOptions) (pb.TokenizationRespons
 	return pb.TokenizationResponse{}, fmt.Errorf("unimplemented")
 }
 
+func (llm *Base) Detokenize(req *pb.DetokenizeRequest) (pb.DetokenizeResponse, error) {
+	return pb.DetokenizeResponse{}, fmt.Errorf("unimplemented")
+}
+
 func (llm *Base) ModelMetadata(opts *pb.ModelOptions) (*pb.ModelMetadataResponse, error) {
 	return nil, fmt.Errorf("unimplemented")
 }

pkg/grpc/client.go

@@ -409,6 +409,28 @@ func (c *Client) TokenizeString(ctx context.Context, in *pb.PredictOptions, opts
 	return res, nil
 }
 
+func (c *Client) Detokenize(ctx context.Context, in *pb.DetokenizeRequest, opts ...grpc.CallOption) (*pb.DetokenizeResponse, error) {
+	if !c.parallel {
+		c.opMutex.Lock()
+		defer c.opMutex.Unlock()
+	}
+	c.setBusy(true)
+	defer c.setBusy(false)
+	defer c.wdMark()()
+	conn, err := c.dial()
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = conn.Close() }()
+	client := pb.NewBackendClient(conn)
+
+	res, err := client.Detokenize(ctx, in, opts...)
+	if err != nil {
+		return nil, err
+	}
+	return res, nil
+}
+
 func (c *Client) Status(ctx context.Context) (*pb.StatusResponse, error) {
 	if !c.parallel {
 		c.opMutex.Lock()

pkg/grpc/embed.go

@@ -113,6 +113,10 @@ func (e *embedBackend) TokenizeString(ctx context.Context, in *pb.PredictOptions
 	return e.s.TokenizeString(ctx, in)
 }
 
+func (e *embedBackend) Detokenize(ctx context.Context, in *pb.DetokenizeRequest, opts ...grpc.CallOption) (*pb.DetokenizeResponse, error) {
+	return e.s.Detokenize(ctx, in)
+}
+
 func (e *embedBackend) Status(ctx context.Context) (*pb.StatusResponse, error) {
 	return e.s.Status(ctx, &pb.HealthMessage{})
 }

pkg/grpc/interface.go

@@ -32,6 +32,7 @@ type AIModel interface {
 	TTSStream(*pb.TTSRequest, chan []byte) error
 	SoundGeneration(*pb.SoundGenerationRequest) error
 	TokenizeString(*pb.PredictOptions) (pb.TokenizationResponse, error)
+	Detokenize(*pb.DetokenizeRequest) (pb.DetokenizeResponse, error)
 	Status() (pb.StatusResponse, error)
 
 	StoresSet(*pb.StoresSetOptions) error

pkg/grpc/server.go

@@ -532,6 +532,18 @@ func (s *server) TokenizeString(ctx context.Context, in *pb.PredictOptions) (*pb
 	}, err
 }
 
+func (s *server) Detokenize(ctx context.Context, in *pb.DetokenizeRequest) (*pb.DetokenizeResponse, error) {
+	if s.llm.Locking() {
+		s.llm.Lock()
+		defer s.llm.Unlock()
+	}
+	res, err := s.llm.Detokenize(in)
+	if err != nil {
+		return nil, err
+	}
+	return &res, nil
+}
+
 func (s *server) Status(ctx context.Context, in *pb.HealthMessage) (*pb.StatusResponse, error) {
 	res, err := s.llm.Status()
 	if err != nil {

swagger/docs.go

@@ -2707,6 +2707,33 @@ const docTemplate = `{
                 }
             }
         },
+        "/v1/detokenize": {
+            "post": {
+                "tags": [
+                    "tokenize"
+                ],
+                "summary": "Detokenize the input.",
+                "parameters": [
+                    {
+                        "description": "Request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/schema.DetokenizeRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Response",
+                        "schema": {
+                            "$ref": "#/definitions/schema.DetokenizeResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/v1/edits": {
             "post": {
                 "tags": [
@@ -4801,6 +4828,30 @@ const docTemplate = `{
                 }
             }
         },
+        "schema.DetokenizeRequest": {
+            "type": "object",
+            "properties": {
+                "model": {
+                    "type": "string"
+                },
+                "tokens": {
+                    "description": "token IDs to convert back to text",
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                }
+            }
+        },
+        "schema.DetokenizeResponse": {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "description": "detokenized text",
+                    "type": "string"
+                }
+            }
+        },
         "schema.DiarizationResult": {
             "type": "object",
             "properties": {