An elegant, idiomatic Go client for the Hugging Face Text Embeddings Inference (TEI) service, supporting both HTTP REST and gRPC transports. Simplify your workflow by choosing the interface that best fits your use case.
.
├── proto/ # Auto-generated protobuf code
│ ├── tei.proto # gRPC + HTTP OpenAPI definitions
│ ├── tei.pb.go # Go structs + HTTP client interfaces
│ └── tei_grpc.pb.go # Go gRPC client stubs
├── teiapi/ # HTTP REST client implementation
│ └── api.go # HTTP client wrapper
└── teigrpc/ # gRPC client implementation
└── grpc.go # gRPC client wrapper
- Dual Transport: Use HTTP REST or gRPC with the same protobuf definitions.
- Unified API: Access Info, Embed, Predict, Rerank, Tokenize, and Decode endpoints.
- Streaming Support: Bidirectional streaming for large or batched operations.
- Context-aware: Pass
context.Contextto manage timeouts and cancellations. - Lightweight: Zero external dependencies beyond
grpc-goand the standard library.
go get -u github.com/atopx/teiclientpackage main
import (
"context"
"fmt"
"time"
"github.com/atopx/teiclient/teiapi"
"github.com/atopx/teiclient/proto"
)
func main() {
// 1. Create HTTP client
client := teiapi.New("http://localhost:8080", 30*time.Second)
// 2. Info
infoResp, err := client.Info(context.Background(), &proto.InfoRequest{})
if err != nil {
panic(err)
}
fmt.Println("Model ID:", infoResp.ModelId)
// 3. Embed
embedReq := &proto.EmbedRequest{Inputs: "Hello, HTTP!", Normalize: true}
embedResp, err := client.Embed(context.Background(), embedReq)
if err != nil {
panic(err)
}
fmt.Printf("Embedding length: %d\n", len(embedResp.Embeddings))
}package main
import (
"context"
"fmt"
"time"
"github.com/atopx/teiclient/teigrpc"
"github.com/atopx/teiclient/proto"
)
func main() {
// 1. Create gRPC client
client, err := teigrpc.New("localhost:50051")
if err != nil {
panic(err)
}
defer client.Close()
// 2. Rerank
rerankReq := &proto.RerankRequest{
Query: "search term",
Texts: []string{"A", "B"},
ReturnText: true,
}
rerankResp, err := client.Rerank(context.Background(), rerankReq)
if err != nil {
panic(err)
}
for _, r := range rerankResp.Ranks {
fmt.Printf("#%d: %s (%.2f)\n", r.Index, r.Text, r.Score)
}
}All methods correspond to tei.proto definitions. Key interfaces:
-
HTTP client in
teiapi/api.gouses methods:Info(ctx, *InfoRequest) (*InfoResponse, error)Embed(ctx, *EmbedRequest) (*EmbedResponse, error)Predict(ctx, *PredictRequest) (*PredictResponse, error)Rerank(ctx, *RerankRequest) (*RerankResponse, error)Tokenize(ctx, *EncodeRequest) (*EncodeResponse, error)Decode(ctx, *DecodeRequest) (*DecodeResponse, error)
-
gRPC client in
teigrpc/grpc.goexposes:Info,Embed,EmbedStream,Predict,PredictStream,Rerank,RerankStream,Tokenize,Decode, etc.
Refer to the GoDoc for full signatures and streaming variants.
Contributions, issues, and feature requests are welcome! Please open a GitHub issue or submit a pull request.
MIT. See LICENSE.