C++ 封装 C FFI 接口最佳实践：以 Hugging Face Tokenizer 为例

1. 引入

在现代 AI 工程中，Hugging Face 的 tokenizers 库已成为分词器的事实标准。不过 Hugging Face 的 tokenizers 是用 Rust 来实现的，官方只提供了 python 和 node 的绑定实现。要实现与 Hugging Face tokenizers 相同的行为，最好的办法就是自己封装 Hugging Face tokenizers 的 C 绑定，从而可以被 C++ / C# / Java 这些高级编程语言调用。
2. 封装 C 接口

首先要说明的是，要做的不是完整的封装 Hugging Face tokenizers 的 C 的 FFI（Foreign Function Interface）接口，而是封装自己需要的接口就可以了。比如执行分词接口和计算Token的接口：

1. use std::ffi::CStr;
2. use std::os::raw::c_char;
3. use tokenizers::{PaddingParams, Tokenizer, TruncationParams};
5. // === 1. 定义 C 兼容的返回结构体 ===
6. #[repr(C)]
7. pub struct TokenizerResult {
8.     pub input_ids: *mut i64,
9.     pub attention_mask: *mut i64,
10.     pub token_type_ids: *mut i64,
11.     pub length: u64,
12. }
14. // === 2. 内部状态：包装 Tokenizer ===
15. struct TokenizerHandle {
16.     tokenizer: Tokenizer,     // 用于 encode（带 padding）
17.     raw_tokenizer: Tokenizer, // 用于 count（无 padding）
18. }
20. // === 3. 辅助函数：将 Rust Vec 转为 C 可拥有的指针 ===
21. fn vec_to_c_ptr(vec: Vec<i64>) -> *mut i64 {
22.     let mut boxed = vec.into_boxed_slice();
23.     let ptr = boxed.as_mut_ptr();
24.     std::mem::forget(boxed); // 防止 Rust 自动释放
25.     ptr
26. }
28. // === 4. 创建 tokenizer ===
29. #[unsafe(no_mangle)] // 禁用 name mangling，让 C 能找到符号
30. pub extern "C" fn tokenizer_create(tokenizer_json_path: *const c_char) -> *mut std::ffi::c_void {
31.     if tokenizer_json_path.is_null() {
32.         return std::ptr::null_mut();
33.     }
35.     let path_cstr = unsafe { CStr::from_ptr(tokenizer_json_path) };
36.     let path_str = match path_cstr.to_str() {
37.         Ok(s) => s,
38.         Err(_) => return std::ptr::null_mut(),
39.     };
41.     let mut tokenizer = match Tokenizer::from_file(path_str) {
42.         Ok(t) => t,
43.         Err(_) => return std::ptr::null_mut(),
44.     };
46.     // 设置 padding/truncation 到 512（BGE 默认）
47.     tokenizer.with_padding(Some(PaddingParams {
48.         strategy: tokenizers::PaddingStrategy::Fixed(512),
49.         ..Default::default()
50.     }));
52.     if tokenizer
53.         .with_truncation(Some(TruncationParams {
54.             max_length: 512,
55.             ..Default::default()
56.         }))
57.         .is_err()
58.     {
59.         return std::ptr::null_mut();
60.     }
62.     let mut raw_tokenizer = tokenizer.clone();
63.     raw_tokenizer.with_padding(None);
64.     raw_tokenizer.with_truncation(None).ok();
66.     let handle = TokenizerHandle {
67.         tokenizer,
68.         raw_tokenizer,
69.     };
70.     Box::into_raw(Box::new(handle)) as *mut std::ffi::c_void
71. }
73. //计算句子token
74. #[unsafe(no_mangle)] // 禁用 name mangling，让 C 能找到符号
75. pub extern "C" fn tokenizer_count(handle: *mut std::ffi::c_void, text: *const c_char) -> u64 {
76.     if handle.is_null() || text.is_null() {
77.         return 0;
78.     }
80.     let handle_ref = unsafe { &*(handle as *mut TokenizerHandle) };
82.     let text_cstr = unsafe { CStr::from_ptr(text) };
83.     let text_str = match text_cstr.to_str() {
84.         Ok(s) => s,
85.         Err(_) => return 0,
86.     };
88.     match handle_ref.raw_tokenizer.encode(text_str, true) {
89.         Ok(encoding) => encoding.len() as u64,
90.         Err(_) => 0,
91.     }
92. }
94. // === 5. 销毁 tokenizer ===
95. #[unsafe(no_mangle)]
96. pub extern "C" fn tokenizer_destroy(handle: *mut std::ffi::c_void) {
97.     if !handle.is_null() {
98.         unsafe {
99.             let _ = Box::from_raw(handle as *mut TokenizerHandle);
100.             // Drop 自动调用
101.         }
102.     }
103. }
105. // === 6. 执行分词 ===
106. #[unsafe(no_mangle)]
107. pub extern "C" fn tokenizer_encode(
108.     handle: *mut std::ffi::c_void,
109.     text: *const c_char,
110. ) -> TokenizerResult {
111.     let default_result = TokenizerResult {
112.         input_ids: std::ptr::null_mut(),
113.         attention_mask: std::ptr::null_mut(),
114.         token_type_ids: std::ptr::null_mut(),
115.         length: 0,
116.     };
118.     if handle.is_null() || text.is_null() {
119.         return default_result;
120.     }
122.     let handle_ref = unsafe { &*(handle as *mut TokenizerHandle) };
124.     let text_cstr = unsafe { CStr::from_ptr(text) };
125.     let text_str = match text_cstr.to_str() {
126.         Ok(s) => s,
127.         Err(_) => return default_result,
128.     };
130.     let encoding = match handle_ref.tokenizer.encode(text_str, true) {
131.         Ok(e) => e,
132.         Err(_) => return default_result,
133.     };
135.     let input_ids: Vec<i64> = encoding.get_ids().iter().map(|&x| x as i64).collect();
136.     let attention_mask: Vec<i64> = encoding
137.         .get_attention_mask()
138.         .iter()
139.         .map(|&x| x as i64)
140.         .collect();
141.     let token_type_ids: Vec<i64> = encoding.get_type_ids().iter().map(|&x| x as i64).collect();
142.     // BGE 不需要，但 C++ 代码传了
143.     // let token_type_ids: Vec<u32> = vec![0u32; input_ids.len()];
145.     let len = input_ids.len(); // 应该是 512，但更通用
147.     TokenizerResult {
148.         input_ids: vec_to_c_ptr(input_ids),
149.         attention_mask: vec_to_c_ptr(attention_mask),
150.         token_type_ids: vec_to_c_ptr(token_type_ids),
151.         length: len as u64,
152.     }
153. }
155. // === 7. 释放结果内存 ===
156. #[unsafe(no_mangle)]
157. pub extern "C" fn tokenizer_result_free(result: TokenizerResult) {
158.     if !result.input_ids.is_null() {
159.         unsafe {
160.             let _ = Vec::from_raw_parts(
161.                 result.input_ids,
162.                 result.length as usize,
163.                 result.length as usize,
164.             );
165.         }
166.     }
168.     if !result.attention_mask.is_null() {
169.         unsafe {
170.             let _ = Vec::from_raw_parts(
171.                 result.attention_mask,
172.                 result.length as usize,
173.                 result.length as usize,
174.             );
175.         }
176.     }
178.     if !result.token_type_ids.is_null() {
179.         unsafe {
180.             let _ = Vec::from_raw_parts(
181.                 result.token_type_ids,
182.                 result.length as usize,
183.                 result.length as usize,
184.             );
185.         }
186.     }
187. }

复制代码

对应的 C 接口如下：

1. // tokenizer_result.h
2. #pragma once
4. struct TokenizerResult {
5.   int64_t* input_ids;
6.   int64_t* attention_mask;
7.   int64_t* token_type_ids;
8.   uint64_t length;
9. };
11. #ifdef __cplusplus
12. static_assert(std::is_standard_layout_v<TokenizerResult> &&
13.                   std::is_trivially_copyable_v<TokenizerResult>,
14.               "TokenizerResult must be C ABI compatible");
15. #endif

复制代码

1. // hf_tokenizer_ffi.h
2. #pragma once
4. #include <stdint.h>
6. #include "tokenizer_result.h"
8. #ifdef __cplusplus
9. extern "C" {
10. #endif
12. void* tokenizer_create(const char* tokenizer_json_path);
13. void tokenizer_destroy(void* handle);
14. TokenizerResult tokenizer_encode(void* handle, const char* text);
15. uint64_t tokenizer_count(void* handle, const char* text);
16. void tokenizer_result_free(TokenizerResult result);
18. #ifdef __cplusplus
19. }
20. #endif

复制代码

具体的封装细节笔者就不多说了，因为与本文的主题无关。不过可以稍稍了解一下其中的原理，也就是说，操作系统大多数是由 C 实现的，或者提供了 C 的接口。因此，绝大多数比 C 高级的编程语言都提供了与 C 交互的能力，当然前提是必须得按照 C 得规范组织数据和封装接口。比如这里的struct TokenizerResult就是一个兼容 C 的结构体，#[unsafe(no_mangle)]则表明这是一个 C 语言形式的函数接口。
3. 经典 C++ 封装

如上接口是一个标准的 C 风格式的接口：将分词器封装成一个 Handle ，也就是俗称的句柄。而后续具体的分词操作就通过这个句柄来进行，包括最后对资源的释放。在 C++ 中，当然也可以直接使用这种形式的接口，不过这样就需要遵循 C 的资源控制规则：资源申请和释放必须成对出现——比如这里的 tokenizer_create 和 tokenizer_destroy。
3.1 RAII 机制

不过这样就会有一个问题，过程式的流程中很难保证 tokenizer_create 和 tokenizer_destroy 能够成对调用，例如：

1. tokenizer_create()
3. if(...){
4.     return;
5. }
7. tokenizer_destroy()

复制代码

只要在 tokenizer_create 和 tokenizer_destroy 之间出现分支，程序提前返回，就会导致资源没有释放而内存泄漏。为了避免这个问题，就需要在每次 return 之前，都调用 tokenizer_destroy()——这当然是非常不优雅的，既容易忘掉又是冗余代码。
为了解决这种资源管理难题，C++ 提供了一种强大而优雅的机制：RAII（Resource Acquisition Is Initialization，资源获取即初始化）。它的核心思想是：将资源的生命周期绑定到对象的生命周期上。具体来说，就是利用面向对象的思想，将资源控制的行为封装成一个类对象，并且保证资源在对象构造函数中获取，在析构函数中自动释放。由于 C++ 中栈对象在离开作用域时会自动调用析构函数，在离开作用域时会自动调用析构函数。因此这些资源总是可以被正确释放，从根本上杜绝内存泄漏或资源泄露。例如：

1. Tokenizer tokenizer;
3. //...操作
5. if(...){
6.     return;
7. }
9. //...更多操作

复制代码

3.2 拷贝语义

复习一下 C++ 面向对象设计的经典五法则（Rule of Five），如果一个类自定义了以下任意一个函数：

• 析构函数（Destructor）
  
• 拷贝构造函数（Copy Constructor）
  
• 拷贝赋值运算符（Copy Assignment Operator）
  
• 移动构造函数（Move Constructor）
  
• 移动赋值运算符（Move Assignment Operator）
  

那么大概率也需要自定义另外四个函数，或者显式 = default / = delete 来控制行为。很多 C++ 程序员并不理解移动语义，但这并没有关系，我们可以先假定不定义移动构造函数和移动赋值运算符（或者显式 = default），此时移动操作就会退化为拷贝语义的行为。
而关于拷贝语义，绝大多数 C++ 程序员应该都知道这个问题：当在类对象中管理资源时，编译器生成的默认拷贝行为是“浅拷贝”，可能导致双重释放、内存泄漏等问题，因此需要自定义拷贝构造函数和拷贝赋值运算符来实现“深拷贝”的行为。因此，这个链条就很明确了：因为类中需要定义析构函数，所以需要同时定义拷贝构造函数和拷贝赋值运算符。
3.3 移动语义

进一步讨论，反正移动语义可以默认，那么是不是只用定义拷贝语义就行了呢？这个要看资源的定义：如果只是管理内存资源，那么这样做是没有问题的，至少是安全的。但是资源管理不仅仅指的是内存资源，还可以是一些文件句柄、网络连接等等。这些资源往往是独占性的，进行深拷贝往往会出现问题。因此就出现了 C++ 11 开始规定的移动语义：可以安全得实现“浅拷贝”的行为。同时还可以解决“深拷贝”的性能问题。
基于以上的思想，笔者封装的分词器对象如下：

1. // HfTokenizer.h
2. #pragma once
4. #include <string>
6. #include "hf_tokenizer_ffi.h"
8. namespace hf {
9. class Tokenizer {
10. public:
11.   explicit Tokenizer(const std::string& path);
13.   // 析构函数
14.   ~Tokenizer() noexcept;
16.   // 禁止拷贝
17.   Tokenizer(const Tokenizer&) = delete;
18.   Tokenizer& operator=(const Tokenizer&) = delete;
20.   // 移动语义
21.   Tokenizer(Tokenizer&& rhs) noexcept;
22.   Tokenizer& operator=(Tokenizer&& rhs) noexcept;
24.   // 其他接口方法
25.   // TokenizerResult Encode(const char* text) const;
26.   // uint64_t Count(const char* text) const;
28. private:
29.   void* handle;  // 来自 tokenizer_create 的指针
30. };
32. }  // namespace hf

复制代码

1. // HfTokenizer.cpp
2. #include "HfTokenizer.h"
4. #include <iostream>
6. namespace hf {
7. Tokenizer::Tokenizer(const std::string& path)
8.     : handle(tokenizer_create(path.c_str())) {
9.   if (!handle) {
10.     throw std::runtime_error("Failed to create tokenizer from " + path);
11.   }
12. }
14. Tokenizer::~Tokenizer() noexcept {
15.   if (handle) {
16.     tokenizer_destroy(handle);
17.   }
18. }
20. // 移动语义
21. Tokenizer::Tokenizer(Tokenizer&& rhs) noexcept : handle(rhs.handle) {
22.   rhs.handle = nullptr;
23. }
25. Tokenizer& Tokenizer::operator=(Tokenizer&& rhs) noexcept {
26.   if (this != &rhs) {
27.     if (handle) {
28.       tokenizer_destroy(handle);
29.     }
30.     handle = rhs.handle;
31.     rhs.handle = nullptr;
32.   }
33.   return *this;
34. }
36. }  // namespace hf

复制代码

如前所述，因为封装的是一个句柄，为了避免资源控制的麻烦，就禁止掉拷贝语义：

1. // 禁止拷贝
2. Tokenizer(const Tokenizer&) = delete;
3. Tokenizer& operator=(const Tokenizer&) = delete;

复制代码

进行()拷贝构造或者=赋值构造看起来似乎很简单，其实在代码层层嵌套之后，就可能很难分析出是不是调用了默认的拷贝的行为，比如函数传参、容器操作等等。当然深拷贝的实现也不是性能最优，因此干脆就直接删除掉拷贝构造函数和拷贝赋值运算符。
没有拷贝语义，那么就需要移动语义来进行传递对象了。其实移动语义没那么难，我们只要把握住一点，移动语义的目的是安全地实现“浅拷贝”。以移动赋值运算符的实现来说，如果要实现如下移动赋值：

1. Tokenizer A();
2. Tokenizer B();
3. B = std::move(A);

复制代码

就需要以下的行为：

• 释放掉B管理的资源。
  
• 将A中的成员“浅拷贝”到B中，让B接管A的资源。
  
• 将A中成员初始化。
  

具体实现就是如下所示：

1. Tokenizer& Tokenizer::operator=(Tokenizer&& rhs) noexcept {
2.   if (this != &rhs) {
3.     if (handle) {
4.       tokenizer_destroy(handle);
5.     }
6.     handle = rhs.handle;
7.     rhs.handle = nullptr;
8.   }
9.   return *this;
10. }

复制代码

移动构造函数就更加简单了，因为B对象在移动构造之前成员并没有初始化：

1. Tokenizer A();
2. Tokenizer B(std::move(A));

复制代码

因此可以省略掉释放自身资源的步骤，具体实现也就是如下所示：

1. Tokenizer::Tokenizer(Tokenizer&& rhs) noexcept : handle(rhs.handle) {
2.   rhs.handle = nullptr;
3. }

复制代码

最后还有一个问题：A通过移动语义转移到B了，A还能使用吗？不能也没必要使用A了，无论是A对象和B对象其实是一个栈对象（当然内部管理的数据成员可能放在堆上），或者说是一个值对象；这跟引用对象或者地址对象完全不同。移动语义的本质是对象所有权的转移，转移之后原对象中资源所有权就不存在了，即使强行访问，要么访问不到，要么会程序崩溃。
4. 高级 C++ 封装

4.1 零法则

使用 RAII 机制 + 经典五法则来设计一个类对象，还有一个优点，就是使用这个类对象作为数据成员的类，就不用再显式实现析构函数。不用显式实现析构函数，也就意味着不用实现拷贝语义和移动语义，完全可以依赖类对象拷贝和移动的默认行为。举例来说，一个MyResource对象，管理着一段内存 buffer ，它的类定义为：

1. class MyResource {
2. public:
3.     // 构造：申请资源
4.     MyResource() {
5.         data = new int[100];
6.     }
8.     // 析构：释放资源
9.     ~MyResource() {
10.         delete[] data;
11.     }
13.     // 拷贝构造：深拷贝
14.     MyResource(const MyResource& other) {
15.         data = new int[100];
16.         copy(other.data, other.data + 100, data);
17.     }
19.     // 拷贝赋值
20.     MyResource& operator=(const MyResource& other) {
21.         if (this != &other) {
22.             delete[] data;
23.             data = new int[100];
24.             copy(other.data, other.data + 100, data);
25.         }
26.         return *this;
27.     }
29.     // 移动构造：接管资源
30.     MyResource(MyResource&& other) noexcept {
31.         data = other.data;
32.         other.data = nullptr;
33.     }
35.     // 移动赋值
36.     MyResource& operator=(MyResource&& other) noexcept {
37.         if (this != &other) {
38.             delete[] data;
39.             data = other.data;
40.             other.data = nullptr;
41.         }
42.         return *this;
43.     }
45. private:
46.     int* data = nullptr;
47. };

复制代码

但是如果我使用 std 容器vector ，相应的代码就可以简写为：

1. #include <vector>
3. class MyResource {
4. public:
5.     // 构造：自动分配内存
6.     MyResource() : data(100) {}  // vector<int> 自动初始化为 100 个元素
8.     // ✅ 无需显式定义析构函数
9.     // ✅ 无需自定义拷贝构造 / 拷贝赋值
10.     // ✅ 无需自定义移动构造 / 移动赋值
12.     // 编译器自动生成的版本已正确、高效、异常安全
14. private:
15.     std::vector<int> data;  // RAII 自动管理内存
16. };

复制代码

这不是因为 vector 使用了什么魔法，而是 vector 本身就是使用了 RAII 机制 + 经典五法则来设计的一个模板类对象！在 MyResource 对象进行拷贝或者移动的时候，作为数据成员，std::vector data也会采取同样的拷贝或者移动的行为，并且默认的、由编译器自动生成的版本就可以正确处理。
以上这个思想，就是现代 C++ 更推荐的零法则（Rule of Zero）：尽量不要手动管理资源，而是使用 RAII 类型让编译器自动生成所有特殊成员函数。而这个 RAII 类型，可以是 std 的任何容器对象、智能指针，也可以是自己按照五法则实现的类对象。
4.2 智能指针

回到本文引入的问题，如果我的分词器实现不像写拷贝语义和移动语义怎么办呢？毕竟都是样板代码，写不好还容易出问题。此时我们就可以使用智能指针 unique_ptr 。常规意义上，我们都知道智能指针可以在没有任何其他对象引用的情况下自动 delete ，其实智能指针还可以自定义资源的释放行为：

1. #pragma once
3. #include <memory>
4. #include <string>
6. namespace hf {
7. class Tokenizer {
8. public:
9.   explicit Tokenizer(const std::string& path);
11.   // 编译器自动生成：
12.   // - 析构函数
13.   // - 移动构造 / 移动赋值
14.   // - 禁止拷贝（因为 unique_ptr 不可拷贝）
16. private:
17.   std::unique_ptr<void, void (*)(void*)> handle;
18. };
20. }  // namespace hf

复制代码

1. #include "HfTokenizer.h"
3. #include <stdexcept>
5. #include "hf_tokenizer_ffi.h"
7. namespace hf {
9. static void HandleDeleter(void* handle) noexcept {
10.   if (handle) {
11.     tokenizer_destroy(handle);
12.   }
13. }
15. Tokenizer::Tokenizer(const std::string& path)
16.     : handle(tokenizer_create(path.c_str()), HandleDeleter) {
17.   if (!handle) {
18.     throw std::runtime_error("Failed to create tokenizer from " + path);
19.   }
20. }
22. }  // namespace hf

复制代码

如上实现所示，函数 HandleDeleter 就是 std::unique_ptr handle 的自定义析构行为，在类对象析构的时候就会自动调用这个函数释放资源。既然资源被智能托管了，那么自然就不用写析构函数；析构函数不用写，那么拷贝构造函数、拷贝赋值运算符、移动构造函数以及移动赋值运算符都可以不用实现，全部可以依赖编译器自动生成。当然，由于 unique_ptr 只能移动不能拷贝，Tokenizer也就只能移动不能拷贝。
5. 总结

最后，笔者就给出 C++ 封装 C FFI 接口的完整实现，如下所示：

1. // HfTokenizer.h
2. #pragma once
4. #include <memory>
5. #include <string>
7. #include "tokenizer_result.h"
9. namespace hf {
10. class Tokenizer {
11. public:
12.   explicit Tokenizer(const std::string& path);
14.   // 编译器自动生成：
15.   // - 析构函数（调用 Deleter）
16.   // - 移动构造 / 移动赋值
17.   // - 禁止拷贝（因为 unique_ptr 不可拷贝）
19.   // 其他接口方法
20.   uint64_t Count(const std::string& text) const;
22.   // 向量化
23.   using ResultPtr =
24.       std::unique_ptr<TokenizerResult, void (*)(TokenizerResult*)>;
25.   ResultPtr Encode(const std::string& text) const;
27. private:
28.   std::unique_ptr<void, void (*)(void*)> handle;
29. };
31. }  // namespace hf

复制代码

1. // HfTokenizer.cpp
2. #include "HfTokenizer.h"
4. #include <stdexcept>
6. #include "hf_tokenizer_ffi.h"
8. namespace hf {
10. static void HandleDeleter(void* handle) noexcept {
11.   if (handle) {
12.     tokenizer_destroy(handle);
13.   }
14. }
16. static void ResultDeleter(TokenizerResult* p) noexcept {
17.   if (p) {
18.     tokenizer_result_free(*p);
19.     delete p;
20.   }
21. }
23. Tokenizer::Tokenizer(const std::string& path)
24.     : handle(tokenizer_create(path.c_str()), HandleDeleter) {
25.   if (!handle) {
26.     throw std::runtime_error("Failed to create tokenizer from " + path);
27.   }
28. }
30. uint64_t Tokenizer::Count(const std::string& text) const {
31.   return tokenizer_count(handle.get(), text.c_str());
32. }
34. Tokenizer::ResultPtr Tokenizer::Encode(const std::string& text) const {
35.   auto result = std::make_unique<TokenizerResult>(
36.       tokenizer_encode(handle.get(), text.c_str()));
37.   return {result.release(), ResultDeleter};
38. };
40. }  // namespace hf

复制代码

不仅是句柄，连传递的数据对象笔者都托管给智能指针，从而避免大量写特殊成员函数这些样板代码。不得不说，RAII 的设计思路非常精妙，同时保证了安全性与简洁性，给人一种回归编程原始状态的感觉。所谓“大道至简”，不是代码越繁复就越安全，也不是代码越抽象就越厉害；真正好的代码，是在正确性、可维护性与简洁性之间取得平衡，让资源管理如呼吸般自然，而非负担。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

喜欢鼓捣这些软件，现在用得少，谢谢分享！

感谢分享，下载保存了，貌似很强大