使用 LLM 命令行工具进行文本嵌入：从 CLI 命令到 Python API 的完整指南-二趣网

使用 LLM 命令行工具进行文本嵌入：从 CLI 命令到 Python API 的完整指南

【免费下载链接】llmAccess large language models from the command-line项目地址: https://gitcode.com/gh_mirrors/llm/llm

本指南以docs/embeddings/index.md及其子页面（docs/embeddings/cli.md、docs/embeddings/python-api.md、docs/embeddings/writing-plugins.md、docs/embeddings/storage.md）为核心，系统讲解 LLM 项目中的嵌入（Embeddings）能力：如何把文本甚至图片转换为浮点向量、如何把向量存储进 SQLite 集合、如何做语义相似度搜索，以及如何通过插件接入新的嵌入模型。读完本文，你将能熟练使用llm embed、llm embed-multi、llm similar等命令，能用 Python API 管理集合，还能自己编写一个嵌入模型插件。

什么是 Embeddings

嵌入模型（Embedding Model）可以把一段文本——一个单词、一句话、一个段落甚至整篇文章——转换成一个浮点数数组。这个数组被称为"嵌入向量"（embedding vector），它是内容语义意义在一个高维空间中的数值化表示。

通过计算嵌入向量之间的距离，我们可以判断哪些内容在语义上与其他内容"最近"。这一能力可以用来构建"相关文章推荐"之类的功能，也可以用来构建语义搜索（semantic search）：用户可以搜索一个短语，即使结果与搜索词不共享任何精确关键词，也能返回语义相似的匹配项。

部分嵌入模型（例如 CLIP 这类多模态模型）甚至可以直接处理图片等二进制文件，从而实现"以图搜图"，或者"用一段文字搜索语义相近的图片"。

LLM 通过插件机制支持多种嵌入模型（参见插件体系）。安装插件后，嵌入模型即可在命令行或 Python API 中使用，用来计算并存储内容的嵌入向量，然后对这批向量执行相似度搜索。

LLM 项目将这一整套能力拆分为四个相互衔接的层面，也正是本文的四个主体章节：

命令行工具（docs/embeddings/cli.md）：llm embed、llm embed-multi、llm similar等命令；
Python API（docs/embeddings/python-api.md）：llm.Collection类与模型加载函数；
存储格式（docs/embeddings/storage.md）：向量在 SQLite 中的二进制编码方式；
插件编写（docs/embeddings/writing-plugins.md）：如何接入新的嵌入模型。

命令行：用 llm embed 计算单个向量

llm embed命令用于计算一段内容的嵌入向量，结果可以直接输出到终端、存入 SQLite 数据库，或两者同时进行。

把向量输出到终端

最简单的用法是通过-c/--content选项传入内容：

llm embed -c 'This is some content' -m 3-small

这里的-m 3-small指定了 OpenAI 的text-embedding-3-small模型（3-small是该模型在 LLM 中注册的别名）。使用该模型前需要先用llm keys set openai设置 OpenAI API Key。

如果你不想依赖已存储的 key 或环境变量，也可以用--key选项直接传入 API Key。该选项同样适用于llm embed-multi命令。

除了 OpenAI，还可以安装插件使用其他模型。例如 llm-sentence-transformers 插件可以在本机运行 MiniLM-L6 等开源模型：

llm install llm-sentence-transformers llm embed -c 'This is some content' -m sentence-transformers/all-MiniLM-L6-v2

llm embed默认向终端输出一个 JSON 数组：

[0.123, 0.456, 0.789...]

如果你已经设置了默认嵌入模型（见下文llm embed-models default），可以省略-m/--model选项。此外，还可以通过环境变量LLM_EMBEDDING_MODEL为当前 shell 会话设置默认模型：

export LLM_EMBEDDING_MODEL=3-small llm embed -c 'This is some content'

二进制格式输出

除了 JSON 数组，LLM 还提供了一种节省空间的二进制存储格式（详见嵌入存储格式一节）。可以用--format blob输出原始字节、--format hex输出十六进制、--format base64输出 Base64：

llm embed -c 'This is some content' -m 3-small --format base64

输出示例：

8NGzPFtdgTqHcZw7aUT6u+++WrwwpZo8XbSxv...

处理二进制数据

像 llm-clip 这类模型可以直接处理二进制数据（如图片）。用-i加--binary选项传入二进制文件：

llm embed --binary -m clip -i image.jpg

也可以从标准输入读取：

cat image.jpg | llm embed --binary -m clip -i -

把向量存储进 SQLite 集合

嵌入向量只有存下来才有更大的价值——你可以在之后计算不同向量之间的相似度。LLM 引入了集合（collection）的概念：一个集合是由同一个模型生成的、带唯一 ID 的一组嵌入向量。同时，每条嵌入还保存了内容的哈希值，用于后续避免对相同内容重复计算嵌入（去重）。这一去重逻辑在源码中有明确实现：Collection.content_hash()使用 MD5 对文本（UTF-8 编码后）或二进制内容取摘要，Collection.embed()在写入前会先按content_hash查询是否已存在（参见 llm/embeddings.py）。

首先设置默认模型，省去重复指定：

llm embed-models default 3-small

llm embed可以把结果直接存进命名集合：

llm embed quotations philkarlton-1 -c \ 'There are only two hard things in Computer Science: cache invalidation and naming things'

这条命令把给定文本存入quotations集合、ID 为philkarlton-1。第一个参数是集合名，第二个参数是条目 ID。

也可以把内容通过管道输入：

cat one.txt | llm embed files one

这会把one.txt的内容以one为 ID 存入files集合。

需要注意两个行为特征：

集合在第一次被提及时自动创建；
集合的嵌入模型是固定的，即存入该集合的第一条向量所用的模型。上面例子中就是命令运行时处于生效状态的默认模型。

下面这个例子把字符串"my happy hound"以hound为 ID 存入phrases集合，并显式指定模型3-small：

llm embed phrases hound -m 3-small -c 'my happy hound'

默认情况下，嵌入存储于 LLM 管理的用户内容目录下的embeddings.db。运行llm collections path可以查看该目录的具体路径。

如果想把嵌入存到别的 SQLite 数据库，用-d/--database选项传入路径，文件不存在时会自动创建：

llm embed phrases hound -d my-embeddings.db -c 'my happy hound'

这条命令会在当前目录创建my-embeddings.db数据库文件。

同时存储内容与元数据

默认情况下，数据库表只保存条目 ID 和嵌入向量。用--store选项可以把原始文本副本存入content列：

llm embed phrases hound -c 'my happy hound' --store

用--metadata选项可以把包含任意元数据的 JSON 对象存入metadata列。下面的例子同时使用了--store与--metadata：

llm embed phrases hound \ -m 3-small \ -c 'my happy hound' \ --metadata '{"name": "Hound"}' \ --store

这些额外存储的数据会在调用llm similar时一并返回：

llm similar phrases -c 'hound'

{"id": "hound", "score": 0.8484683588631485, "content": "my happy hound", "metadata": {"name": "Hound"}}

命令行：用 llm embed-multi 批量嵌入

llm embed一次只处理一条字符串，而llm embed-multi可以一次性嵌入多条内容，从而利用嵌入模型在处理批量输入时的效率优势。

llm embed-multi有三种调用方式：

传入一个 CSV、TSV、JSON 或换行分隔 JSON（newline-delimited JSON）文件；
传入一个 SQLite 数据库和一条 SQL 查询；
传入一个或多个目录路径，每个目录配一个 glob 模式。

三种方式都支持以下通用选项：

-m model_id：指定嵌入模型；
-d database.db：指定用于存储嵌入的不同数据库文件；
--store：除嵌入向量外，把原始内容也存入嵌入表；
--prefix：为每个条目的 ID 加上前缀；
--prepend：在嵌入前向内容前附加一段字符串；
--batch-size SIZE：按指定大小分批处理嵌入。

--prepend选项对需要"前置特殊 token"的模型尤其有用。例如nomic-embed-text-v2-moe模型要求文档内容以'search_document: '开头、搜索查询以'search_query: '开头。

从 CSV、TSV 或 JSON 文件嵌入

把文件作为第二个参数（集合名之后）传给命令即可。文件必须至少包含两列：第一列是条目 ID，后续所有列都被当作要嵌入的内容。

CSV 文件示例：

id,content one,This is the first item two,This is the second item

TSV 与 CSV 相同，只是用制表符替代逗号。

JSON 文件可以是数组形式：

[ {"id": "one", "content": "This is the first item"}, {"id": "two", "content": "This is the second item"} ]

也可以是换行分隔 JSON：

{"id": "one", "content": "This is the first item"} {"id": "two", "content": "This is the second item"}

无论哪种格式，都可以这样传给llm embed-multi：

llm embed-multi items mydata.csv

第一个参数是集合名，第二个参数是文件名。

也可以把内容通过标准输入管道传入（用-表示标准输入）：

cat mydata.json | llm embed-multi items -

LLM 会自动检测数据格式。如果自动检测失败，可以用--format显式指定。向标准输入管道传入换行分隔 JSON 时必须使用--format：

cat mydata.json | llm embed-multi items - --format nl

其他受支持的--format值还有csv、tsv和json。

下面这个综合示例：把 JSON 文件中的数据嵌入到items集合、数据库为docs.db、模型为3-small，同时把原始内容存进embeddings表，并为每个 ID 加上my-items/前缀：

llm embed-multi items mydata.json \ -d docs.db \ -m 3-small \ --prefix my-items/ \ --store

从 SQLite 数据库嵌入

用--sql选项可以从 SQLite 数据库读取数据，必要时配合--attach附加另一个数据库。

如果源数据与嵌入存储在同一数据库：

llm embed-multi docs \ -d docs.db \ --sql 'select id, title, content from documents' \ -m 3-small

这里的docs.db中含有一个documents表，我们提取其中的title与content两列进行嵌入，结果存回同一数据库。

如果源数据在另一个数据库，用--attach附加，并在 SQL 中使用alias.table形式引用：

llm embed-multi docs \ -d embeddings.db \ --attach other other.db \ --sql 'select id, title, content from other.documents' \ -m 3-small

从目录中的文件嵌入

LLM 可以嵌入指定目录下每个文本文件的内容，以文件路径和文件名作为 ID。假设目录结构如下：

docs/aliases.md docs/contributing.md docs/embeddings/binary.md docs/embeddings/cli.md docs/embeddings/index.md docs/index.md docs/logging.md docs/plugins/directory.md docs/plugins/index.md

要嵌入所有这些文档，可以运行：

llm embed-multi documentation \ -m 3-small \ --files docs '**/*.md' \ -d documentation.db \ --store

这里的--files docs '**/*.md'表示扫描docs目录中匹配**/*.mdglob 模式的文件——该模式会匹配任意嵌套目录下的 Markdown 文件。命令执行后embeddings表将包含如下 ID：

aliases.md contributing.md embeddings/binary.md embeddings/cli.md embeddings/index.md index.md logging.md plugins/directory.md plugins/index.md

每个 ID 对应该文件内容的嵌入。

用--prefix可以为每个 ID 加前缀：

llm embed-multi documentation \ -m 3-small \ --files docs '**/*.md' \ -d documentation.db \ --store \ --prefix llm-docs/

结果 ID 变为：

llm-docs/aliases.md llm-docs/contributing.md llm-docs/embeddings/binary.md llm-docs/embeddings/cli.md llm-docs/embeddings/index.md llm-docs/index.md llm-docs/logging.md llm-docs/plugins/directory.md llm-docs/plugins/index.md

文件默认按 UTF-8 解码；如果遇到编码错误，LLM 会回退到latin-1。可以用--encoding选项指定一组不同的编码，按顺序尝试。下面这个例子先尝试utf-16，再尝试mac_roman，最后回退到latin-1：

llm embed-multi documentation \ -m 3-small \ --files docs '**/*.md' \ -d documentation.db \ --encoding utf-16 \ --encoding mac_roman \ --encoding latin-1

如果某个文件读取失败，错误会记录到标准错误，脚本会继续运行而不会中断。

如果要嵌入图片之类的二进制内容（配合 CLIP 使用），加上--binary选项：

llm embed-multi photos \ -m clip \ --files photos/ '*.jpeg' --binary

命令行：用 llm similar 做相似度搜索

llm similar命令基于余弦相似度（cosine similarity）在嵌入集合中检索与给定内容或条目 ID 最相似的条目。

注意：当前实现采用慢速的暴力遍历（brute-force）方式，对大规模集合扩展性不佳。官方计划通过插件提供的向量索引引入更可扩展的方案。

搜索quotations集合中与'computer science'语义相似的条目：

llm similar quotations -c 'computer science'

该命令先嵌入提供的字符串，然后返回一个换行分隔的 JSON 对象列表：

{"id": "philkarlton-1", "score": 0.8323904531677017, "content": null, "metadata": null}

用-p/--plain可以让结果以纯文本而不是 JSON 返回：

llm similar quotations -c 'computer science' -p

输出示例：

philkarlton-1 (0.8323904531677017)

还可以用-i filename与文件中的文本比较：

llm similar quotations -i one.txt

或者用-i -从标准输入读取文本：

echo 'computer science' | llm similar quotations -i -

使用 CLIP 这类模型时，可以用-i filename加--binary查找与输入图片相似的图片：

llm similar photos -i image.jpg --binary

用--prefix可以只展示 ID 以指定前缀开头的条目：

llm similar quotations --prefix 'movies/' -c 'star wars'

命令行：模型管理与集合管理

llm embed-models：列出可用的嵌入模型

列出所有可用嵌入模型（含插件提供的）：

llm embed-models

输出大致如下：

OpenAIEmbeddingModel: text-embedding-ada-002 (aliases: ada, ada-002) OpenAIEmbeddingModel: text-embedding-3-small (aliases: 3-small) OpenAIEmbeddingModel: text-embedding-3-large (aliases: 3-large) ...

叠加-q可以按关键词过滤模型：

llm embed-models -q 3-small

llm embed-models default：查看与设置默认模型

不带参数返回当前默认模型名称：

llm embed-models default

设置默认模型：

llm embed-models default 3-small

这会把默认模型设为 OpenAI 的3-small模型。模型注册的任何别名都可以传给该命令。

取消默认模型：

llm embed-models default --remove-default

当没有设置默认模型时，llm embed和llm embed-multi命令必须用-m/--model显式指定模型。

llm collections：管理集合

列出嵌入数据库中的所有集合：

llm collections list

加--json输出 JSON 格式：

llm collections list --json

加-d/--database指定不同的数据库文件：

llm collections list -d my-embeddings.db

删除集合：

llm collections delete collection-name

同样支持-d指定数据库文件：

llm collections delete collection-name -d my-embeddings.db

Python API：加载模型与计算向量

除命令行外，LLM 还提供完整的 Python API。加载嵌入模型（按模型 ID 或别名）：

import llm embedding_model = llm.get_embedding_model("3-small")

调用.embed()方法嵌入字符串，返回 Python 浮点数列表：

vector = embedding_model.embed("my happy hound")

可以用key=直接传 API Key——既可以是 Key 本身，也可以是通过llm keys set存储的 Key 别名：

vector = embedding_model.embed("my happy hound", key="sk-...")

如果模型支持二进制输入，可以把字节串传给.embed()。用supports_binary属性判断是否支持：

from pathlib import Path if embedding_model.supports_binary: vector = embedding_model.embed(Path("my-image.jpg").read_bytes())

embedding_model.supports_text属性则表明模型是否支持文本输入。

许多嵌入模型在批量处理多条内容时效率更高。要一次嵌入多条字符串，用.embed_multi()方法：

vectors = list(embedding_model.embed_multi(["my happy hound", "my dissatisfied cat"]))

它返回一个生成器，为每条字符串产出一个嵌入向量。embed_multi()也接受与embed()相同的key=参数。

嵌入按批次计算。默认所有内容在单个批次中处理，除非底层模型自己定义了首选批次大小（例如 OpenAI 系列模型的batch_size为 100，参见 llm/default_plugins/openai_models.py）。可以用batch_size=N自定义批次大小：

vectors = list(embedding_model.embed_multi(lines_from_file, batch_size=20))

从源码看，EmbeddingModel.embed_multi()会根据self.batch_size（模型定义）或调用方传入的batch_size用islice分批调用_embed_batch()（参见 llm/models.py）。

Python API：用 Collection 类管理集合

llm.Collection类用于在 Python 代码中操作嵌入集合。集合是一组命名嵌入向量，与各自的 ID 一起存储在 SQLite 数据库表中。

使用它需要一个 sqlite-utils Database 实例，再连同集合名和所用嵌入模型的 ID 一起传给llm.Collection构造函数：

import sqlite_utils import llm # 使用内存数据库，进程退出即丢弃 collection = llm.Collection("entries", model_id="3-small") # 或者持久化到磁盘： db = sqlite_utils.Database("my-embeddings.db") collection = llm.Collection("entries", db, model_id="3-small") # 也可以用 model= 直接传模型实例，替代 model_id= embedding_model = llm.get_embedding_model("3-small") collection = llm.Collection("entries", db, model=embedding_model)

如果集合已存在于数据库中，可以省略model或model_id参数——模型 ID 会从collections表读取。

嵌入单条字符串并存入集合，用embed()方法：

collection.embed("hound", "my happy hound")

这会把"my happy hound"的嵌入以hound为 ID 存入entries集合。

可以传key="..."直接指定 API Key，collection.embed_multi()和collection.embed_multi_with_metadata()也接受该参数。

加store=True可以把文本内容本身与嵌入向量一起存入数据库表。要给条目附加额外元数据，把 JSON 兼容字典作为metadata=参数：

collection.embed("hound", "my happy hound", metadata={"name": "Hound"}, store=True)

元数据会以 JSON 形式存储在嵌入数据库表的metadata列中。

批量存储

collection.embed_multi()可以一次存储多个条目的嵌入，对部分模型效率更高：

collection.embed_multi( [ ("hound", "my happy hound"), ("cat", "my dissatisfied cat"), ], # 加上这行以把字符串存入 content 列： store=True, )

要为每条内容附带元数据，调用embed_multi_with_metadata()：

collection.embed_multi_with_metadata( [ ("hound", "my happy hound", {"name": "Hound"}), ("cat", "my dissatisfied cat", {"name": "Cat"}), ], # 这里同样可以加 store=True： store=True, )

batch_size=参数默认为 100，除非嵌入模型自身定义了更小的批次大小。在嵌入大规模集合遇到内存问题时，可以调小该值：

collection.embed_multi( ( (i, line) for i, line in enumerate(lines_in_file) ), batch_size=10 )

从源码看，embed_multi_with_metadata()会先计算所有条目的content_hash，跳过已存在的 ID 以去重，再按min(batch_size, model.batch_size)分批调用模型并原子写入数据库（参见 llm/embeddings.py）。测试 tests/test_embed.py 验证了默认批次（100 条一批共 100 批）与自定义批次（batch_size=5时 200 批）两种场景下 1000 条数据全部正确入库。

Collection 类参考

一个集合实例具有以下属性和方法：

id—— 集合在数据库中的整数 ID；
name—— 集合的字符串名称（数据库中唯一）；
model_id—— 该集合所用嵌入模型的字符串 ID；
model()—— 根据model_id返回对应的EmbeddingModel实例；
count()—— 返回集合中的条目数；
embed(id: str, value: str | bytes, metadata: dict[str, Any] | None = None, store: bool = False, *, key: str | None = None)—— 嵌入给定值并以指定 ID 存入集合；可选附带元数据（存为 JSON）、把文本或二进制内容存入表、传入 API Key 或已存储 Key 别名；
embed_multi(entries: Iterable[tuple[str, str | bytes]], store: bool = False, batch_size: int = 100, *, key: str | None = None)—— 见上文；
embed_multi_with_metadata(entries: Iterable[tuple[str, str | bytes, dict[str, Any] | None]], store: bool = False, batch_size: int = 100, *, key: str | None = None)—— 见上文；
similar(value: str | bytes, number: int = 10, prefix: str | None = None)—— 返回与给定值嵌入最相似的条目列表；
similar_by_id(id: str, number: int = 10, prefix: str | None = None)—— 返回与指定 ID 条目的嵌入最相似的条目列表；
similar_by_vector(vector: list[float], number: int = 10, skip_id: str | None = None, prefix: str | None = None)—— 返回与给定嵌入向量最相似的条目列表，可跳过指定 ID 的条目；
delete()—— 从数据库删除集合及其嵌入。

此外还有Collection.exists(db, name)类方法，返回布尔值，用于判断集合在数据库中是否存在：

if Collection.exists(db, "entries"): print("The entries collection exists")

需要说明的是，Collection构造函数的create=False参数（源码见 llm/embeddings.py）可以在集合不存在时抛出Collection.DoesNotExist异常，这为只读场景提供了更严格的检查手段。

检索相似条目

集合填充完毕后，用similar()方法检索与给定字符串最相似的条目。

该方法同样是暴力遍历——对每个文档计算距离分数，适合小型集合，大规模集合下扩展性受限。

for entry in collection.similar("hound"): print(entry.id, entry.score)

字符串会先被集合所用模型嵌入。返回的entry对象具有以下属性：

id—— 条目的字符串 ID；
score—— 条目与查询字符串之间的浮点相似度分数；
content—— 条目的文本内容（如果存过），否则为None；
metadata—— 条目的元数据字典（来自 JSON），如果存过，否则为None。

默认返回最相似的 10 条，可以用number=修改：

for entry in collection.similar("hound", number=5): print(entry.id, entry.score)

similar_by_id()接受集合中另一个条目的 ID，基于其已存储的嵌入返回最相似条目（该条目自身会从结果中排除）：

for entry in collection.similar_by_id("cat"): print(entry.id, entry.score)

源码中similar_by_vector()把余弦相似度注册为 SQLite 函数后直接在 SQL 中排序取前 N 条（参见 llm/embeddings.py）；cosine_similarity()的具体实现在 llm/init.py。测试 tests/test_embed.py 验证了similar、带前缀过滤的similar以及similar_by_id三种检索路径。

SQL schema：嵌入数据库的表结构

嵌入数据库使用如下 SQL schema（由迁移脚本 llm/embeddings_migrations.py 逐步构建）：

CREATE TABLE "collections" ( "id" INTEGER PRIMARY KEY, "name" TEXT, "model" TEXT ) CREATE TABLE "embeddings" ( "collection_id" INTEGER REFERENCES "collections"("id"), "id" TEXT, "embedding" BLOB, "content" TEXT, "content_blob" BLOB, "content_hash" BLOB, "metadata" TEXT, "updated" INTEGER, PRIMARY KEY ("collection_id", "id") )

两点值得注意：

collections.name建有唯一索引，保证集合名唯一；embeddings表以(collection_id, id)为联合主键；
迁移从m001（建表）一路演进到m005（新增content_blob列），逐步加入了外键约束、updated时间戳列与content_hash去重列，因此老数据库可以通过迁移平滑升级。

存储格式：向量的二进制编码

llm embed命令的默认输出是浮点数 JSON 数组，但 LLM 在存储时使用更节省空间的格式：小端序的 32 位浮点数二进制序列，每个浮点数占 4 字节，存放在 SQLite 的BLOB列中。

以下 Python 函数可以在该格式与浮点数数组之间互相转换：

import struct def encode(values): return struct.pack("<" + "f" * len(values), *values) def decode(binary): return struct.unpack("<" + "f" * (len(binary) // 4), binary)

这两个函数在 LLM 中可直接使用，即llm.encode()和llm.decode()（实现见 llm/init.py）。如果使用 NumPy，可以这样解码一个二进制值：

import numpy as np numpy_array = np.frombuffer(value, "<f4")

这里的<f4格式串让 NumPy 把数据按小端序 32 位浮点数序列处理。

编写插件：接入新的嵌入模型

编写插件接入新嵌入模型前，建议先阅读插件开发教程（见 docs/plugins/tutorial-model-plugin.md）了解插件的开发与打包流程。

一个嵌入模型插件由两个部分组成：

register_embedding_models()钩子的实现：接收一个register回调函数，调用它把新模型注册进 LLM 插件系统；
一个继承llm.EmbeddingModel抽象基类的类：该基类唯一必须实现的方法是embed_batch(texts)，它接收一个字符串可迭代对象，返回浮点数列表的迭代器。

下面的示例使用 sentence-transformers 包提供 MiniLM-L6 嵌入模型：

import llm from sentence_transformers import SentenceTransformer @llm.hookimpl def register_embedding_models(register): model_id = "sentence-transformers/all-MiniLM-L6-v2" register(SentenceTransformerModel(model_id, model_id), aliases=("all-MiniLM-L6-v2",)) class SentenceTransformerModel(llm.EmbeddingModel): def __init__(self, model_id, model_name): self.model_id = model_id self.model_name = model_name self._model = None def embed_batch(self, texts): if self._model is None: self._model = SentenceTransformer(self.model_name) results = self._model.encode(texts) return (list(map(float, result)) for result in results)

调用托管 API 的嵌入模型应设置needs_key（及可选的key_env_var），并在embed_batch()中接受关键字参数key=。LLM 会在调用该方法前解析显式 Key、已存储 Key 别名和环境变量：

class HostedEmbeddingModel(llm.EmbeddingModel): model_id = "hosted-embedding-model" needs_key = "hosted" key_env_var = "HOSTED_API_KEY" def embed_batch(self, texts, *, key=None): # key 是解析后的 API Key results = hosted_client.embed(texts, api_key=key) return (list(map(float, result)) for result in results)

key=的值可以来自llm embed --key、llm embed-multi --key，或 Python 侧的embed(..., key=)与embed_multi(..., key=)。为了兼容旧插件，LLM 也支持embed_batch()不接受key=参数的插件——此时解析后的 Key 会临时暴露为self.key（兼容逻辑见 llm/models.py）。

插件安装后，其模型即可配合llm embed命令使用：

cat file.txt | llm embed -m sentence-transformers/all-MiniLM-L6-v2

或使用注册的别名：

cat file.txt | llm embed -m all-MiniLM-L6-v2

支持二进制内容

如果模型可以嵌入二进制内容，用supports_binary属性声明：

class ClipEmbeddingModel(llm.EmbeddingModel): model_id = "clip" supports_binary = True supports_text= True

supports_text默认就是True，此处可不写；如果模型只支持二进制，可以把它设为False。

如果模型接受二进制输入，你的.embed_batch()可能会收到 Python 字节串列表；若模型同时接受两种类型，这些字节串可能与普通字符串混在一起。

从基类源码看，EmbeddingModel还声明了batch_size类属性（默认None，表示不限制批次），以及_check()对文本/二进制支持性的运行时校验（参见 llm/models.py）；OpenAIEmbeddingModel是needs_key、key_env_var与batch_size三者配合使用的现成范例（参见 llm/default_plugins/openai_models.py）。测试 tests/test_embed.py 还覆盖了"仅二进制模型"与"仅文本模型"的边界场景。

企业官网建设流程全解析