为什么现代 C++ 库都用 PIMPL？一场关于封装、依赖与安全的演进

class FileHandle {
    FILE* fp;
public:
    FileHandle(const char* path) : fp(fopen(path, "r")) {}
    ~FileHandle() { if (fp) fclose(fp); }
};

class Embedder {
    Ort::Session session; // 值成员
public:
    std::vector<float> embed(const std::string& text);
};

// header
class SessionImpl; // 前置声明
class Embedder {
    SessionImpl* pimpl;
public:
    Embedder();
    ~Embedder(); // 必须手动 delete
};

class SessionImpl;
class Embedder {
    std::unique_ptr<SessionImpl> pimpl;
};

// Embedder.cpp
class Embedder::Impl {
    // 完整定义...
};

Embedder::~Embedder() = default; // ✅ 此时 Impl 完整，安全析构

// 头文件
class Embedder {
    class Impl;
    std::unique_ptr<Impl> impl;
public:
    Embedder(const std::string& model);
    ~Embedder(); // 声明但不在头文件定义！
    std::vector<float> embed(std::string_view text) const;
};

// 源文件
class Embedder::Impl {
    Ort::Session session;
    hf::Tokenizer tokenizer;
    int64_t dim;
public:
    Impl(const std::string& path, const hf::Tokenizer& tok) 
        : session(...), tokenizer(tok) { /* init */ }
    std::vector<float> embed(std::string_view text) const { /* ... */ }
};

Embedder::Embedder(const std::string& path) 
    : impl(std::make_unique<Impl>(path, global_tokenizer)) {}

Embedder::~Embedder() = default; // 此时 Impl 完整，安全！

// BgeOnnxEmbedder.h
#pragma once

#include <memory>
#include <string>
#include <vector>

namespace embedding {

namespace hf {
class Tokenizer;
}

class BgeOnnxEmbedder {
 public:
  explicit BgeOnnxEmbedder(const std::string& modelPath,
                           const hf::Tokenizer& tokenizer);
  ~BgeOnnxEmbedder();

  const int64_t& EmbeddingDim() const;

  std::vector<float> Embed(const std::string& text) const;

 private:
  class Impl;  // 前向声明
  std::unique_ptr<Impl> impl;
};

}  // namespace embedding

//BgeOnnxEmbedder.cpp
#include "BgeOnnxEmbedder.h"

#include <onnxruntime_cxx_api.h>

#include "HfTokenizer.h"
#include "Util/StringEncode.h"

namespace embedding {

class BgeOnnxEmbedder::Impl {
 public:
  Ort::Env& GetOrtEnv() {
    static Ort::Env env(ORT_LOGGING_LEVEL_WARNING, "BgeOnnxEmbedder");
    return env;
  }

  const int64_t& EmbeddingDim() const { return embeddingDim; }

  explicit Impl(const std::string& modelPath, const hf::Tokenizer& tokenizer)
      : session{GetOrtEnv(),
#ifdef _WIN32
                util::StringEncode::Utf8StringToWideString(modelPath).c_str(),
#else
                modelPath.c_str(),
#endif
                Ort::SessionOptions()},
        memInfo{Ort::MemoryInfo::CreateCpu(OrtDeviceAllocator, OrtMemTypeCPU)},
        tokenizer(tokenizer),
        embeddingDim(0) {

    //
    const auto& outputInfo = session.GetOutputTypeInfo(0);
    const auto& tensorInfo = outputInfo.GetTensorTypeAndShapeInfo();
    const auto& shape = tensorInfo.GetShape();

    // 假设输出是 [batch, seq, dim] 或 [batch, dim]
    // 我们取最后一个非 -1 的维度
    for (auto it = shape.rbegin(); it != shape.rend(); ++it) {
      if (*it != -1) {
        embeddingDim = *it;
        break;
      }
    }

    if (embeddingDim == 0) {
      throw std::runtime_error(
          "Failed to infer embedding dimension from ONNX model.");
    }
  }

  std::vector<float> Embed(const std::string& text) const {
    hf::Tokenizer::ResultPtr result = tokenizer.Encode(text);
    if (!result) {
      throw std::runtime_error("tokenizer_encode failed");
    }

    // 定义张量维度
    int64_t seqLen = static_cast<int64_t>(result->length);
    std::vector<int64_t> inputShape = {1, seqLen};
    size_t dataByteCount = sizeof(int64_t) * seqLen;

    Ort::Value inputIdsTensor = Ort::Value::CreateTensor(
        memInfo.GetConst(), result->input_ids, dataByteCount, inputShape.data(),
        inputShape.size(),
        ONNXTensorElementDataType::ONNX_TENSOR_ELEMENT_DATA_TYPE_INT64);

    Ort::Value attentionMaskTensor = Ort::Value::CreateTensor(
        memInfo.GetConst(), result->attention_mask, dataByteCount,
        inputShape.data(), inputShape.size(),
        ONNXTensorElementDataType::ONNX_TENSOR_ELEMENT_DATA_TYPE_INT64);

    Ort::Value tokenTypeIdsTensor = Ort::Value::CreateTensor(
        memInfo.GetConst(), result->token_type_ids, dataByteCount,
        inputShape.data(), inputShape.size(),
        ONNXTensorElementDataType::ONNX_TENSOR_ELEMENT_DATA_TYPE_INT64);

    // 输入名必须与模型定义一致
    const char* inputNames[] = {"input_ids", "attention_mask",
                                "token_type_ids"};
    const char* outputNames[] = {"last_hidden_state"};

    // 把三个输入张量放进数组
    std::vector<Ort::Value> inputs;
    inputs.push_back(std::move(inputIdsTensor));
    inputs.push_back(std::move(attentionMaskTensor));
    inputs.push_back(std::move(tokenTypeIdsTensor));

    // 执行推理
    auto outputs = session.Run(Ort::RunOptions(),  // 运行选项（通常 nullptr）
                               inputNames,         // 输入名数组
                               inputs.data(),  // 输入张量数组
                               inputs.size(),  // 输入数量（3）
                               outputNames,    // 输出名数组
                               1               // 输出数量（1）
    );

    // 获取输出信息
    auto& output_tensor = outputs[0];
    auto output_shape = output_tensor.GetTensorTypeAndShapeInfo().GetShape();
    if (output_shape.size() != 3 || output_shape[0] != 1) {
      throw std::runtime_error("Unexpected output shape");
    }

    // 获取输出张量的原始 float 指针
    const float* outputData = outputs[0].GetTensorData<float>();

    // 提取 [CLS] token 的 embedding（第0个token）
    int64_t hiddenSize = output_shape[2];
    std::vector<float> embedding(outputData, outputData + hiddenSize);

    // L2 归一化（BGE 要求）
    float norm = 0.0f;
    for (float v : embedding) norm += v * v;
    norm = std::sqrt(norm);
    if (norm > 1e-8) {
      for (float& v : embedding) v /= norm;
    }

    return embedding;
  }

 private:
  mutable Ort::Session session;
  Ort::MemoryInfo memInfo;
  const hf::Tokenizer& tokenizer;
  int64_t embeddingDim;
};

BgeOnnxEmbedder::BgeOnnxEmbedder(const std::string& modelPath,
                                 const hf::Tokenizer& tokenizer)
    : impl(std::make_unique<Impl>(modelPath, tokenizer)) {}

BgeOnnxEmbedder::~BgeOnnxEmbedder() = default;  // 此时 Impl 已定义，可安全析构

const int64_t& BgeOnnxEmbedder::EmbeddingDim() const {
  return impl->EmbeddingDim();
}

std::vector<float> BgeOnnxEmbedder::Embed(const std::string& text) const {
  return impl->Embed(text);
}

}  // namespace embedding