片段#

LLM 提示词可以选择由片段组成 - 这些是可重用的文本片段，只会被记录到数据库一次，然后可以附加到多个提示词中。

当你使用长上下文模型时，这尤其有用，这类模型支持将大量文本作为提示词的一部分输入。

片段主要用于节省数据库空间，但也可能用于支持其他功能，例如供应商提示词缓存。

可以使用几种不同的机制来指定片段

在线文本文件的 URL
磁盘上文本文件的路径
已附加到特定片段的别名
存储片段的哈希 ID，其中 ID 是片段内容的 SHA256 哈希值
自定义插件提供的片段 - 它们看起来像 plugin-name:argument

在提示词中使用片段#

使用 -f/--fragment 选项来指定一个或多个要作为提示词一部分使用的片段

llm -f https://llm.datasette.com.cn/robots.txt "Explain this robots.txt file in detail"

这里我们使用 URL 指定一个片段。该 URL 的内容将包含在发送给模型的提示词中，放在提示词文本之前。

-f 选项可以多次使用，以组合多个片段。

片段也可以是磁盘上的文件，例如

llm -f setup.py 'extract the metadata'

使用 - 来指定一个将从标准输入读取的片段

llm -f - 'extract the metadata' < setup.py

这将从标准输入读取 setup.py 的内容，并将其用作片段。

片段也可以用作系统提示词的一部分。使用 --sf value 或 --system-fragment value 代替 -f。

浏览片段#

你可以使用 llm fragments 命令查看你之前存储在数据库中的片段的截断版本

llm fragments

该命令的输出如下所示

- hash: 0d6e368f9bc21f8db78c01e192ecf925841a957d8b991f5bf9f6239aa4d81815
  aliases: []
  datetime_utc: '2025-04-06 07:36:53'
  source: https://raw.githubusercontent.com/simonw/llm-docs/refs/heads/main/llm/0.22.txt
  content: |-
    <documents>
    <document index="1">
    <source>docs/aliases.md</source>
    <document_content>
    (aliases)=
    #...
- hash: 16b686067375182573e2aa16b5bfc1e64d48350232535d06444537e51f1fd60c
  aliases: []
  datetime_utc: '2025-04-06 23:03:47'
  source: simonw/files-to-prompt/pyproject.toml
  content: |-
    [project]
    name = "files-to-prompt"
    version = "0.6"
    description = "Concatenate a directory full of...

那些长的 hash 值是将来可用于引用片段的 ID

llm -f 16b686067375182573e2aa16b5bfc1e64d48350232535d06444537e51f1fd60c 'Extract metadata'

多次使用 -q searchterm 来搜索与特定搜索词匹配的片段。

要查看片段的完整内容，请使用 llm fragments show 命令

llm fragments show 0d6e368f9bc21f8db78c01e192ecf925841a957d8b991f5bf9f6239aa4d81815

为片段设置别名#

你可以使用 llm fragments set 命令为你经常使用的片段分配别名

llm fragments set mydocs ./docs.md

要移除别名，请使用 llm fragments remove 命令

llm fragments remove mydocs

然后你可以使用该别名代替片段的哈希 ID

llm -f mydocs 'How do I access metadata?'

使用 llm fragments --aliases 命令查看已分配别名的片段的完整列表

llm fragments --aliases

在日志中查看片段#

llm logs 命令列出用于提示词的片段。默认情况下，这些片段以哈希 ID 列出，但你可以使用 --expand 选项来显示每个片段的完整内容。

此命令将显示用于你最近对话的展开后的片段

llm logs -c --expand

你可以使用 -f/--fragment 选项过滤使用特定片段的日志

llm logs -c -f 0d6e368f9bc21f8db78c01e192ecf925841a957d8b991f5bf9f6239aa4d81815

这接受 URL、文件路径、别名和哈希 ID。

多个 -f 选项将返回使用了指定片段中所有片段的响应。

llm logs --json 命令也会返回片段。默认情况下，这些片段会被截断，但你可以添加 -e/--expand 选项来显示每个片段的完整内容。

llm logs -c --json --expand

从插件使用片段#

LLM 插件可以提供自定义的片段加载器，它们能做一些有用的事情。

一个例子是 llm-fragments-github 插件。这个插件可以将公共 GitHub 仓库中的文件转换为片段列表，从而允许你询问关于整个仓库的问题。

如何尝试：

llm install llm-fragments-github
llm -f github:simonw/s3-credentials 'Suggest new features for this tool'

这个插件将对 -f github:simonw/s3-credentials 的一次调用转换为多个片段，在 simonw/s3-credentials GitHub 仓库中的每个文本文件对应一个片段。

运行 llm logs -c 将显示此提示词包含了 26 个片段，每个文件对应一个。

运行 llm logs -c --usage --expand (快捷方式：llm logs -cue) 会包含 token 使用信息，并将每个片段 ID 转换为该文件的完整副本。这是该命令的输出。

片段插件也可以返回附件 (例如图片)。

参阅 register_fragment_loaders() 插件钩子文档，了解如何编写自己的自定义片段插件的详细信息。

列出可用的片段前缀#

llm fragments loaders 命令显示由插件安装的所有前缀及其文档

llm install llm-fragments-github
llm fragments loaders

示例输出

github:
  Load files from a GitHub repository as fragments

  Argument is a GitHub repository URL or username/repository

issue:
  Fetch GitHub issue and comments as Markdown

  Argument is either "owner/repo/NUMBER"
  or "https://github.com/owner/repo/issues/NUMBER"