PowerInfer 本地文本嵌入实战使用 embedding 示例生成高维文本向量【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址: https://gitcode.com/gh_mirrors/po/PowerInfer导读本文以 examples/embedding 为例讲解如何在 PowerInferllama.cpp 系本地大模型推理框架中将一个文本片段转换为高维嵌入向量embedding vector。文中既包含开箱即用的 Unix/Windows 命令行示例也深入 embedding.cpp 源码剖析从 tokenize、llama_decode 到读取嵌入结果的完整调用链帮助你在本地部署场景中快速落地文本检索、语义相似度计算与 RAG 向量化等应用。一、embedding 示例能做什么embedding 示例演示了使用 llama.cpp 风格接口为给定文本生成高维嵌入向量即句向量。与常规的文本生成不同它不做自回归续写而是让模型一次性编码输入文本并取出模型内部的隐藏层表示作为该文本的向量化结果。输出是一串由空格分隔的浮点数float维度由模型的n_embd决定。这类向量可直接用于语义相似度计算如余弦相似度文本检索与重排RAG检索增强生成中的文档向量化文本聚类、去重等下游任务。在 PowerInfer 中该示例与其他 llama.cpp 生态示例一起通过 examples/CMakeLists.txt 的add_subdirectory(embedding)参与构建。二、快速开始使用前请先构建项目并准备一个本地 GGUF 模型然后将下面的命令中的./path/to/model替换为实际模型路径。Unix 系系统Linux、macOS 等./embedding -m ./path/to/model --log-disable -p Hello World! 2/dev/nullWindowsembedding.exe -m ./path/to/model --log-disable -p Hello World! 2$null命令执行后标准输出stdout即为一串空格分隔的浮点数值。2/dev/nullWindows 下为2$null用于把日志、系统信息等诊断输出重定向到 stderr保证 stdout 中只有纯净的向量数据方便脚本直接解析。三、关键命令行参数embedding 示例通过gpt_params_parse解析参数因此继承了 llama.cpp 公共参数体系常用参数如下参数含义默认值-m, --modelGGUF 模型文件路径必填无-p, --prompt需要向量化的输入文本无可配合--random-prompt--log-disable关闭日志输出由 common/log.h 处理关闭状态--verbose-prompt在 stderr 打印 token 化后的 token 列表便于调试false-b, --batch-size单次解码的 token 数prompt 处理批大小512定义于 common/common.h-c, --context-size上下文窗口大小512定义于 common/common.h-t, --threads计算线程数物理核心数--random-prompt未提供-p时随机生成一个 promptfalse定义于 common/common.h--numa启用 NUMA 优化false定义于 common/common.h其中--log-disable并非公共参数而是由日志模块 common/log.h 单独识别并调用log_disable()因此它不会出现在--help的公共参数列表中但可以直接使用。注意embedding 与文本生成的开关是互斥的。gpt_params中的bool embedding字段默认false见 common/common.h在 common.cpp 中由--embedding参数置位而在 examples/main/main.cpp 中当检测到params.embedding为真时main 示例会提示“please use the embedding tool for embedding calculations”并直接退出把计算任务交给本示例。四、源码流程剖析examples/embedding/embedding.cpp 虽然只有一百余行却完整展示了 llama.cpp 推理 API 的标准用法其核心流程如下。1. 参数解析与初始化gpt_params params; if (!gpt_params_parse(argc, argv, params)) { return 1; } params.embedding true; // 显式开启嵌入模式 print_build_info();无论用户是否传入--embedding程序都会强制将params.embedding置为trueembedding.cpp确保后续创建上下文时分配嵌入缓冲区。若未显式指定随机种子则用当前时间作为seedembedding.cpp并通过std::mt19937初始化随机数生成器当--random-prompt开启时调用gpt_random_prompt(rng)生成随机文本embedding.cpp。2. 加载模型与上下文llama_backend_init(params.numa); std::tie(model, ctx) llama_init_from_gpt_params(params);llama_init_from_gpt_params是公共封装内部会依次完成llama_load_model_from_file加载 GGUF 模型、llama_new_context_with_model创建推理上下文。加载失败时程序报错退出embedding.cpp。创建上下文时embedding标志的作用会体现在内存分配上在 llama.cpp 中if (params.embedding)成立时会执行ctx-embedding.resize(hparams.n_embd)为最终向量预留n_embd个float的存储空间。该嵌入缓冲区还会参与 llama.cpp 中状态保存/加载的序列化流程但推理时仅作为输出载体。随后代码校验上下文窗口const int n_ctx_train llama_n_ctx_train(model); const int n_ctx llama_n_ctx(ctx); if (n_ctx n_ctx_train) { /* 警告模型训练上下文仅为 n_ctx_train */ }即当用户指定的-c超过模型训练时的上下文长度时会向 stderr 输出警告embedding.cpp。3. Token 化输入文本auto embd_inp ::llama_tokenize(ctx, params.prompt, true);llama_tokenize使用模型自带的分词器BPE 或 SentencePiece将 prompt 转为 token 序列true表示该文本是“非特殊 token 的完整输入”。若开启--verbose-prompt会逐 token 打印token id - 文本片段便于核对分词结果embedding.cpp。若 token 数超过n_ctx程序直接报错退出避免越界embedding.cpp。4. 分块解码while (!embd_inp.empty()) { int n_tokens std::min(params.n_batch, (int) embd_inp.size()); if (llama_decode(ctx, llama_batch_get_one(embd_inp.data(), n_tokens, n_past, 0))) { fprintf(stderr, %s : failed to eval\n, __func__); return 1; } n_past n_tokens; embd_inp.erase(embd_inp.begin(), embd_inp.begin() n_tokens); }这里采用“批处理 滑动推进”的方式每次最多喂入params.n_batch个 token默认 512见 common/common.h通过llama_batch_get_one构造单序列 batch其签名见 llama.h调用llama_decode执行前向计算然后以n_past记录已处理的 token 数循环直到全部处理完embedding.cpp。这种分块机制保证超长文本也能在受限的批大小内完成编码。5. 读取嵌入向量并输出const int n_embd llama_n_embd(model); const auto * embeddings llama_get_embeddings(ctx); for (int i 0; i n_embd; i) { printf(%f , embeddings[i]); } printf(\n);llama_n_embd返回模型隐藏层维度llama_get_embeddings声明见 llama.h返回一维[n_embd]数组直接返回 llama.cpp 中ctx-embedding.data()的指针。程序随后以%f逐个打印因此最终输出即为一行空格分隔的浮点数embedding.cpp。6. 收尾llama_print_timings(ctx); llama_free(ctx); llama_free_model(model); llama_backend_free();打印推理耗时统计加载时间、解码 token 数、每 token 耗时等后依次释放上下文、模型并关闭后端embedding.cpp。五、底层原理嵌入向量从哪来从计算图层面看模型的第一次变换发生在 llama.cppinpL ggml_get_rows(ctx, tok_embd, inp_tokens);即通过ggml_get_rows按 token id 从 token embedding 表中取出对应行得到输入表示inpL随后经 Transformer 各层前向传播。本仓库的 PowerInfer 内核会在稀疏算子路径上对这部分计算进行优化包括基于 GPU/CPU 混合的稀疏推理但对外暴露的llama_get_embeddingsAPI 语义保持一致即返回编码完成后累积在ctx-embedding中的最终隐藏状态。需要留意的是不同模型对“句向量”的定义不同。部分模型如 BERT 系默认取[CLS]token 的表示部分模型会做 mean pooling。embedding 示例取的是 llama.cpp 内部在嵌入模式下累积的隐藏层结果具体语义取决于模型在 GGUF 中配置的 pooling 方式。若你的模型需要特定 pooling 策略请以模型文档或转换脚本如 convert-hf-to-powerinfer-gguf.py中的配置为准。六、构建与集成建议embedding 示例通过 CMake 构建其目标定义见 examples/embedding/CMakeLists.txtset(TARGET embedding) add_executable(${TARGET} embedding.cpp) install(TARGETS ${TARGET} RUNTIME) target_link_libraries(${TARGET} PRIVATE common llama ${CMAKE_THREAD_LIBS_INIT}) target_compile_features(${TARGET} PRIVATE cxx_std_11)即生成名为embedding的可执行文件链接common参数解析、系统信息等公共库与llama核心库并要求 C11 标准。构建整个项目后可执行文件通常位于构建目录下的bin/子目录。实际集成到自己的程序时可以参照同样的三步 API 模式用gpt_params_parse或直接填充gpt_params配置参数并置params.embedding truellama_init_from_gpt_params加载模型与上下文llama_tokenize后循环llama_decodellama_get_embeddings(ctx)拿到n_embd维向量用于下游相似度计算或向量入库。七、注意事项输出纯净性向量打印在 stdout日志与统计打印在 stderr脚本化使用时务必用2/dev/null或2$null隔离避免混入噪声。上下文限制输入 token 数不得超过n_ctx超长文本需自行截断或分段-c不建议超过模型的n_ctx_train否则会有训练上下文警告。模型选择请使用支持嵌入任务如带[CLS]/pooling 头、或以 text embedding 为目标微调的模型并确认其 GGUF 中 embedding 相关配置正确导出。与生成模式互斥embedding 计算不产出 tokenmain示例在--embedding下会被引导到本工具避免混淆用途。至此你已经可以在 PowerInfer 本地环境中完成“文本 → 高维向量”的完整流程一条命令快速验证一份 embedding.cpp 源码理解原理并可将其 API 调用模式直接复用到自己的检索、RAG 或语义分析应用中。【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址: https://gitcode.com/gh_mirrors/po/PowerInfer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
