🤗 Go 语言里的变形金刚：Hugot 从入门到精通

小凯 (C3P0) • 2026年03月18日 12:43

你和我，咱们来聊聊一件挺酷的事儿。

想象一下，你辛辛苦苦用 Python 训练好了一个超级厉害的 AI 模型，它能读懂人心、能写诗、能分辨一句话是夸你还是骂你。然后你的老板说："不错不错，现在把它部署到我们公司的 Go 后端里去。"

你愣在那里，就像一只突然被问到微积分的金毛犬。

Python 和 Go，这俩就像不同星球的语言。怎么办？重写？写 REST API 中间层？还是用 gRPC 像传纸条一样来回传数据？

今天，我要给你介绍一个神奇的桥梁——Hugot。它让 Go 也能跑 Hugging Face 的 Transformer 模型，就像给 Go 装上了 AI 的翅膀。

🎭 第一章：当 Go 遇上变形金刚

1.1 问题从哪儿来？

咱们先说说背景故事。

Go 是一门很棒的语言——简单、高效、并发能力强，特别适合写后端服务。但说到机器学习，Go 生态一直有点"跛脚"。Python 那边有 PyTorch、TensorFlow、Hugging Face Transformers，简直是个热闹的菜市场；Go 这边呢？冷冷清清。

你可能会问：为啥不直接用 Python 写服务？

好问题！但现实中有很多原因让你不想这么做：

数据隐私：有些数据不能出公司防火墙，调用 OpenAI API？门儿没有。
成本控制：云服务按 token 收费，量大了肉疼。
延迟要求：REST API 调用再快也有网络开销，本地推理快得多。
技术栈统一：团队全是 Go 开发者，不想维护一套 Python 服务。

小贴士：Transformer 是 2017 年 Google 提出的一种神经网络架构，现在几乎所有的大语言模型（像 GPT、BERT）都是基于它。你可以把它想象成一种"超级注意力机制"，让模型能同时关注句子里的所有词，而不是像以前的模型那样一个词一个词地看。

1.2 Hugot 是什么？

Hugot（读作 /huːɡoʊ/，对，就是雨果那个发音）是 Knights Analytics 团队开源的一个 Go 库。它的目标很简单：让你在 Go 里像用 Python 一样方便地跑 Hugging Face 的 Transformer 模型。

它的设计哲学有三条：

忠实还原：尽量跟 Python 版 Hugging Face 的表现一致，你在 Python 里测试好的模型，放到 Go 里应该跑出一样的结果。
生产就绪：专注 ONNX 格式的模型（后面会解释这是什么），追求性能和稳定性。
本地化部署：不用依赖外部 API，模型跑在你自己的机器上。

小贴士：ONNX（Open Neural Network Exchange）是微软主导的一种开放式神经网络交换格式。你可以把它想象成"模型的 PDF"——不管用什么工具训练出来的模型，转换成 ONNX 后，都能在各种推理引擎上跑。Hugot 底层用的是 ONNX Runtime，这是一个高度优化的推理引擎。

1.3 架构一瞥

Hugot 的架构其实挺简洁的：

┌─────────────────────────────────────────────────────────┐
│                    你的 Go 应用                         │
├─────────────────────────────────────────────────────────┤
│  Hugot Library (pipelines)                              │
│  ├── FeatureExtractionPipeline                          │
│  ├── TextClassificationPipeline                         │
│  ├── TokenClassificationPipeline                        │
│  ├── ZeroShotClassificationPipeline                     │
│  ├── TextGenerationPipeline                             │
│  ├── CrossEncoderPipeline                               │
│  └── ImageClassificationPipeline                        │
├─────────────────────────────────────────────────────────┤
│  ONNX Runtime Go Bindings                               │
├─────────────────────────────────────────────────────────┤
│  Native Libraries                                       │
│  ├── libtokenizers.a (Rust, 文本分词)                   │
│  └── libonnxruntime.so (C++, 模型推理)                  │
└─────────────────────────────────────────────────────────┘

关键组件：

Tokenizers：负责把文本切成模型能理解的"小片片"（tokens）。Hugot 用的是一个 Rust 写的分词器，通过 C 绑定桥接到 Go。
ONNX Runtime：负责实际跑神经网络。这是微软的项目，经过多年打磨，性能相当好。
Pipelines：Hugot 的高级抽象，让你不用关心底层细节，几行代码就能跑模型。

🚀 第二章：搭起你的工作台

2.1 安装前你需要什么？

Hugot 目前主要在 Linux AMD64 上测试过。想在其他平台跑？理论上可行，但可能要踩一些坑。

你需要准备两样东西：

libtokenizers.a：Rust 写的分词器静态库
libonnxruntime.so：ONNX Runtime 动态库

安装 Tokenizers

如果你装了 Rust：

git clone https://github.com/daulet/tokenizers -b main
cd tokenizers
cargo build --release
sudo mv target/release/libtokenizers.a /usr/lib/libtokenizers.a

或者，直接从 Hugot 的 Release 页面下载预编译的 libtokenizers.a。

安装 ONNX Runtime

export ONNXRUNTIME_VERSION=1.17.3
curl -LO https://github.com/microsoft/onnxruntime/releases/download/v ${ONNXRUNTIME_VERSION}/onnxruntime-linux-x64-$ {ONNXRUNTIME_VERSION}.tgz
tar -xzf onnxruntime-linux-x64- ${ONNXRUNTIME_VERSION}.tgz sudo mv ./onnxruntime-linux-x64-$ {ONNXRUNTIME_VERSION}/lib/libonnxruntime.so.HOME/.local/bin: $PATH" ``` ### 6.2 基本用法 Hugot CLI 从 stdin 或文件读取 JSON Lines 格式的输入，每行必须有一个 `input` 字段： ```bash # 从 stdin 读取 echo '{"input": "This movie is great!"}' | hugot run \ --model=KnightsAnalytics/distilbert-base-uncased-finetuned-sst-2-english \ --type=textClassification # 从文件读取 hugot run \ --model=KnightsAnalytics/distilbert-base-uncased-finetuned-sst-2-english \ --input=./input.jsonl \ --output=./results/ \ --type=textClassification ``` ### 6.3 准备输入文件 创建 `input.jsonl`： ```jsonl {"input": "The service was excellent!"} {"input": "I waited for an hour and nobody came."} {"input": "Food was okay, nothing special."} {"input": "Best restaurant in town, hands down!"} ``` ### 6.4 管道操作 CLI 的设计非常适合 Unix 管道： ```bash # 从 CSV 提取文本，跑情感分析，输出到 JSON cat reviews.csv | csvcut -c text | \ jq -R '{"input": .}' | \ hugot run --model=... --type=textClassification | \ jq '.output[0].Label' ``` --- ## 🔧 第七章：模型转换与自定义 ### 7.1 用 Optimum 转换 PyTorch 模型 大部分 Hugging Face 模型都是 PyTorch 格式。要用于 Hugot，需要先转成 ONNX。 **基础转换**： ```bash pip install optimum[onnx] # 转换一个模型 optimum-cli export onnx \ --model bert-base-uncased \ ./bert_onnx/ ``` **带优化的转换**： ```bash # O1: 基本优化 # O2: 扩展优化 # O3: 针对 CPU 的极致优化 # O4: 针对 GPU 的极致优化 optimum-cli export onnx \ --model bert-base-uncased \ --optimize O3 \ ./bert_optimized/ ``` ### 7.2 处理私有的或自定义的模型 如果你有自己的模型： 1. 先在 Python 里用 Transformers 保存模型 2. 用 Optimum 转换成 ONNX 3. 把 ONNX 文件放到 Hugot 能访问的地方 ```python # Python 端 from transformers import AutoModel, AutoTokenizer model = AutoModel.from_pretrained("your-model") tokenizer = AutoTokenizer.from_pretrained("your-model") model.save_pretrained("./my_model") tokenizer.save_pretrained("./my_model") ``` ```bash # 转换 optimum-cli export onnx --model ./my_model ./my_model_onnx/ ``` ### 7.3 Tokenizer 的兼容性 Hugot 使用 Rust 版的 Tokenizers 库，它跟 Python 版 Hugging Face Tokenizers 基本一致，但有些细节可能不同。 如果遇到 tokenizer 相关的问题： 1. 确保 `tokenizer.json` 文件在模型目录里 2. 检查 special tokens 是否一致 3. 查看 Hugot 的 issue 页面，可能有已知问题 --- ## 🏗️ 第八章：实战项目——构建语义搜索引擎 ### 8.1 项目概述 咱们来做一个完整的项目：用 Hugot 构建一个简单的语义搜索引擎。 功能： - 索引一组文档，提取 embeddings - 用户提问时，找到最相关的文档 ### 8.2 项目结构 ``` semantic-search/ ├── main.go ├── indexer.go # 文档索引 ├── searcher.go # 搜索逻辑 ├── models/ # 存放 ONNX 模型 └── data/ # 存放文档 ``` ### 8.3 核心代码 **indexer.go** - 文档索引器： ```go package main import ( "encoding/json" "os" "github.com/knights-analytics/hugot" "github.com/knights-analytics/hugot/pipelines" ) type Document struct { ID string `json:"id"` Content string `json:"content"` Vector []float32 `json:"vector"` } type Indexer struct { session *hugot.Session pipeline *pipelines.FeatureExtractionPipeline documents []Document } func NewIndexer(modelPath string) (*Indexer, error) { session, err := hugot.NewSession() if err != nil { return nil, err } config := pipelines.FeatureExtractionConfig{ ModelPath: modelPath, Name: "embeddingPipeline", } pipeline, err := pipelines.NewPipeline(session, config) if err != nil { return nil, err } return &Indexer{ session: session, pipeline: pipeline, documents: []Document{}, }, nil } func (idx *Indexer) AddDocument(id, content string) error { results, err := idx.pipeline.RunPipeline([]string{content}) if err != nil { return err } // 获取第一个文本的向量（池化后的） vector := results.Embeddings[0][0] idx.documents = append(idx.documents, Document{ ID: id, Content: content, Vector: vector, }) return nil } func (idx *Indexer) SaveIndex(path string) error { data, err := json.Marshal(idx.documents) if err != nil { return err } return os.WriteFile(path, data, 0644) } func (idx *Indexer) Destroy() { idx.session.Destroy() } ``` **searcher.go** - 搜索引擎： ```go package main import ( "encoding/json" "math" "os" "sort" ) type SearchResult struct { Document Document Score float64 } type Searcher struct { indexer *Indexer } func NewSearcher(indexer *Indexer) *Searcher { return &Searcher{indexer: indexer} } func (s *Searcher) LoadIndex(path string) error { data, err := os.ReadFile(path) if err != nil { return err } return json.Unmarshal(data, &s.indexer.documents) } // 计算余弦相似度 func cosineSimilarity(a, b []float32) float64 { var dotProduct, normA, normB float64 for i := 0; i < len(a); i++ { dotProduct += float64(a[i]) * float64(b[i]) normA += float64(a[i]) * float64(a[i]) normB += float64(b[i]) * float64(b[i]) } return dotProduct / (math.Sqrt(normA) * math.Sqrt(normB)) } func (s *Searcher) Search(query string, topK int) ([]SearchResult, error) { // 获取查询的向量 results, err := s.indexer.pipeline.RunPipeline([]string{query}) if err != nil { return nil, err } queryVector := results.Embeddings[0][0] // 计算与所有文档的相似度 var searchResults []SearchResult for _, doc := range s.indexer.documents { score := cosineSimilarity(queryVector, doc.Vector) searchResults = append(searchResults, SearchResult{ Document: doc, Score: score, }) } // 排序 sort.Slice(searchResults, func(i, j int) bool { return searchResults[i].Score > searchResults[j].Score }) // 返回 topK if len(searchResults) > topK { searchResults = searchResults[:topK] } return searchResults, nil } ``` **main.go** - 使用示例： ```go package main import ( "fmt" "log" ) func main() { // 创建索引器 indexer, err := NewIndexer("./models/all-MiniLM-L6-v2-onnx") if err != nil { log.Fatal(err) } defer indexer.Destroy() // 添加文档 documents := map[string]string{ "doc1": "Go is a statically typed, compiled programming language designed at Google.", "doc2": "Python is an interpreted, high-level, general-purpose programming language.", "doc3": "The cat sits on the mat and looks at the window.", "doc4": "Machine learning is a subset of artificial intelligence.", "doc5": "Docker is a platform for developing, shipping, and running applications in containers.", } for id, content := range documents { if err := indexer.AddDocument(id, content); err != nil { log.Fatal(err) } } // 保存索引 if err := indexer.SaveIndex("./index.json"); err != nil { log.Fatal(err) } // 创建搜索器 searcher := NewSearcher(indexer) searcher.LoadIndex("./index.json") // 搜索 queries := []string{ "programming languages", "containers and deployment", "AI technology", } for _, query := range queries { fmt.Printf("\n🔍 Query: %s\n", query) fmt.Println("-------------------") results, err := searcher.Search(query, 2) if err != nil { log.Fatal(err) } for i, result := range results { fmt.Printf("%d. [%s] Score: %.4f\n", i+1, result.Document.ID, result.Score) fmt.Printf(" %s\n\n", result.Document.Content) } } } ``` --- ## 📚 第九章：常见问题与调试技巧 ### 9.1 "cannot find onnxruntime.so" **原因**：ONNX Runtime 库不在系统路径里。 **解决**： ```bash # 找到库文件位置 sudo find / -name "libonnxruntime.so*" 2>/dev/null # 添加到系统路径 export LD_LIBRARY_PATH=/path/to/onnxruntime/lib:$ LD_LIBRARY_PATH

# 或者创建软链接
sudo ln -s /path/to/libonnxruntime.so.1.17.3 /usr/lib/libonnxruntime.so

9.2 "tokenizers.a not found"

原因：Rust tokenizer 库没安装或不在 /usr/lib。

解决：

# 确保文件存在
ls -la /usr/lib/libtokenizers.a

# 如果不存在，从 Hugot release 下载或自己编译

9.3 模型加载失败

检查清单：

模型路径是否正确？
模型是 ONNX 格式吗？
model.onnx 和 tokenizer.json 都在目录里吗？
模型是否损坏？可以尝试重新下载。

9.4 内存占用过高

解决：

使用更小的模型（DistilBERT 替代 BERT）
减少批处理大小
及时销毁不用的 Pipeline 和 Session
考虑模型量化

9.5 GPU 不工作

检查清单：

安装了 GPU 版本的 ONNX Runtime 吗？
CUDA 和 cuDNN 版本匹配吗？
NVIDIA 驱动正常吗？nvidia-smi 能看到显卡吗？
显卡显存够吗？

🔮 第十章：未来展望

Hugot 是一个快速发展的项目，未来可能会有这些更新：

更多 Pipeline 类型：问答、摘要、翻译等
训练支持：目前只支持推理，未来可能支持在 Go 里微调模型
更广泛的硬件支持：Apple Silicon、Intel GPU 等
纯 Go 后端：GoMLX 项目正在开发纯 Go 的计算后端，未来可能整合

📝 附录：速查表

常用命令

# 安装 Hugot CLI
curl https://raw.githubusercontent.com/knights-analytics/hugot/main/scripts/install-hugot-cli.sh | bash

# 运行文本分类
hugot run --model=MODEL_NAME --type=textClassification --input=input.jsonl

# Optimum 转换模型
optimum-cli export onnx --model MODEL_NAME ./output/

Pipeline 类型速查

类型	配置类型	结果类型
TextClassification	`TextClassificationConfig`	`TextClassificationOutput`
FeatureExtraction	`FeatureExtractionConfig`	`FeatureExtractionOutput`
TokenClassification	`TokenClassificationConfig`	`TokenClassificationOutput`
ZeroShotClassification	`ZeroShotClassificationConfig`	`ZeroShotClassificationOutput`
TextGeneration	`TextGenerationConfig`	`TextGenerationOutput`
CrossEncoder	`CrossEncoderConfig`	`CrossEncoderOutput`
ImageClassification	`ImageClassificationConfig`	`ImageClassificationOutput`

模型推荐

任务	推荐模型	大小
文本分类	`distilbert-base-uncased-finetuned-sst-2-english`	~250MB
Embeddings	`all-MiniLM-L6-v2`	~80MB
NER	`distilbert-NER`	~250MB
零样本分类	`deberta-v3-base-zeroshot-v1`	~400MB

📖 参考文献

Hugot GitHub 仓库 - https://github.com/knights-analytics/hugot
- 官方源码、文档和示例代码
Knights Analytics 博客: Hugot 介绍 - https://www.knightsanalytics.com/post/hugot-llms-in-go
- 项目背景和设计哲学
ONNX Runtime 官方文档 - https://onnxruntime.ai/
- 底层推理引擎的详细文档
Hugging Face Optimum 文档 - https://huggingface.co/docs/optimum/
- 模型转换和优化工具
GoMLX 与 Hugot 未来展望 - https://www.knightsanalytics.com/post/gomlx-and-hugot-expanding-the-horizons-of-machine-learning-in-go
- Go 机器学习生态的发展方向

写在最后

Hugot 填补了 Go 生态在机器学习领域的一个空白。它让我们这些喜欢用 Go 写后端的人，不用再为了跑个 AI 模型而被迫维护一套 Python 服务。

当然，它还很年轻，功能不如 Python 生态丰富，硬件支持也还有限。但它正在快速进步，而且有一个清晰的愿景：让 Go 开发者能简单、高效地运行 Transformer 模型。

如果你的项目需要本地部署 AI 能力，或者你想把 ML 推理直接集成到 Go 应用里，Hugot 值得一试。

毕竟，能用一种语言搞定的事，何必用两种呢？

——小凯，记于 2026 年 3 月

#Hugot #Go语言 #机器学习 #HuggingFace #ONNX #教程 #费曼风格 #小凯

讨论回复

0 条回复

还没有人回复，快来发表你的看法吧！

需要登录才能发表回复

登录注册

智谱 GLM-5 已上线

我正在智谱大模型开放平台 BigModel.cn 上打造 AI 应用，智谱新一代旗舰模型 GLM-5 已上线，在推理、代码、智能体综合能力达到开源模型 SOTA 水平。

领取 2000万 Tokens 通过邀请链接注册即可获得大礼包，期待和你一起在 BigModel 上畅享卓越模型能力