如何帮助 LLM 理解你的 nbdev 项目

一份实用指南，教你如何使用 llms.txt 让你的 nbdev 库对 LLM 友好，并包含自动化技术和实现示例。
作者

Radek Osmulski

发布于

2024年1月20日

概述

本教程演示了如何将 llms.txt 添加到您的 nbdev 项目中，从而在您的代码和 LLM 之间创建一个清晰的接口。您将学习如何生成 llms-ctx.txt 和 llms-ctx-full.txt 文件，并将它们与您的文档集成。

虽然本指南侧重于 nbdev，但其基本原则和工具是与框架无关的，可以帮助任何代码库更容易被 LLM 访问。

让我们来探究如何实现这一点。

关键要素：llms.txt

LLM 友好文档的基础是 llms.txt 文件。其核心只是一个 Markdown 文件，包含了有关您库的信息，位于一个特定的 URL（您网站的根目录，后跟 /llms.txt）。

然而，它需要遵循 llms.txt 格式中概述的特定结构。

不过，请不要被规范吓到。实际上，它提供了很大的灵活性，通过遵循它，您将能使用几个非常有用的工具，我们稍后会看到。

首先，让我们开始编写我们的 llms.txt 文件。如果您愿意，可以打开您喜欢的编辑器，边看边为您的库编写一个 llms.txt 文件。

下面是 llms.txt 文件的开头示例：

# FastHTML

> FastHTML is a python library which...

When writing FastHTML apps remember to:

- Thing to remember

必需的元素有：

  • H1 标题 (FastHTML)
  • 一个包含项目简短摘要的引用块 (FastHTML 是一个 python 库，它…)

它们后面可以跟随零个或多个段落和列表。通常，这里是您添加库简短描述的地方。

描述可以非常简单（这是 fastcore 的 llms.txt 文件摘录）：

Here are some tips on using fastcore:

- **Liberal imports**: Utilize `from fastcore.module import *` freely. The library is designed for safe wildcard imports.
- **Enhanced list operations**: Substitute `list` with `L`. This provides advanced indexing, method chaining, and additional functionality while maintaining list-like behavior.
- **Extend existing classes**: Apply the `@patch` decorator to add methods to classes, including built-ins, without subclassing. This enables more flexible code organization.

以下是一些让描述写作过程更顺畅的想法：

  • 考虑您已有的内容，可以作为起点（例如，您项目的 README、博客文章和文章、社交媒体讨论等）。
  • 想象一下您会如何向新团队成员描述您的库——这通常能在精确性和易理解性之间找到恰当的平衡。
  • 使用 LLM 帮助您将来自多个来源的内容整合成连贯的文章（尽管您可能需要进行一些后期处理，以克服 LLM 倾向于冗长的毛病）。

添加资源章节

在可选的描述之后，您可以包含零个或多个以 H2 标题开头的章节，其中包含指向补充资源的链接。

这里强烈推荐使用 Markdown 文件，因为它们在结构性和可读性之间取得了很好的平衡。您可以尝试链接到其他格式，但结果可能会有所不同。例如，HTML 往往很冗长，而像 CSV 这样的格式很少包含适合于记录功能的信息。

下面是这个章节可能的样子：

## Docs

- [Surreal](https://host/README.md): Tiny jQuery alternative with Locality of Behavior
- [FastHTML quick start](https://host/quickstart.html.md): An overview of FastHTML features

## Examples

- [Todo app](https://host/adv_app.py)

Optional 章节

如果您愿意，可以包含一个标题为 Optional 的章节。这个章节有特殊的含义，提供了一种管理上下文大小的机制。此章节中列出的资源仅出现在 llms-ctx-full.txt 中，而在 llms-ctx.txt 中被省略。这允许用户（无论是人还是代理）根据其用例和计划使用的 LLM 的能力，选择适当的上下文量。

  • llms.txt: 仅包含初始部分，附有可选描述和带有未展开链接的可选资源章节。
  • llms-ctx.txt: 同上，但除了‘Optional’章节外，所有链接都已展开。
  • llms-ctx-full.txt: 所有章节的链接都已展开。

下面是 Optional 章节的一个小示例：

## Optional

- [Starlette docs](https://host/starlette-sml.md): A subset of the Starlette docs

您的 llms.txt 文件现在完成了！是时候为自己出色的工作拍拍背，然后让我们进入下一个自动化步骤。

生成上下文文件

llms-txt 库能自动从您的 llms.txt 生成上下文文件。它可以通过其 CLI 接口或作为 Python 模块使用。

使用 CLI

llms_txt2ctx llms.txt --save_nbdev_fname llms-ctx.txt

或者通过 Python

from llms_txt import *
samp = Path('llms-sample.txt').read_text()
parsed = parse_llms_file(samp)

两种方法都会读取您的 llms.txt 文件并检索链接的内容。这个过程就是将您的 llms.txt 转换为 llms-ctx.txt 和 llms-ctx-full.txt。

但还有另一个非常令人兴奋的库——pysymbol-llm——它将允许我们以自动化的方式添加更多有用的信息。

使用 API 参考增强上下文

虽然 LLM 通常能理解高层次的概念，但它们常常在实现细节上遇到困难，尤其是当它们的训练数据过时时。提供一个包含您库的符号——函数、类及其文档——的全面列表有助于弥合这一差距。

这就是 pysymbol-llm 库发挥作用的地方。它能以 Markdown 格式生成完整的 API 参考，并在此过程中提取现有的文档字符串。

这是 fastcore 的 apilist.txt 文件的一小段摘录：

# fastcore Module Documentation

## fastcore.ansi

> Filters for processing ANSI colors.

- `def strip_ansi(source)`
    Remove ANSI escape codes from text.

- `def ansi2html(text)`
    Convert ANSI colors to HTML colors.

- `def ansi2latex(text)`
    Convert ANSI colors to LaTeX colors.

该工具即使对于大型库也能很好地工作。例如，为 numpy 生成 API 参考只需要一个命令：

pysym2md numpy

要在您的项目中实现这一点，请生成一个 apilist.txt 文件，将其与您的文档一起提供，并在您的 llms.txt 文件中引用它。

配置

最后一步是配置您的 nbdev 项目来生成和提供这些上下文文件。这需要三项更改：

  1. 将您的 llms.txt 文件添加到项目的 nbs 目录中。

  2. 在 settings.ini 中添加所需的依赖项

dev_requirements = pysymbol_llm llms-txt
  1. 在 nbs/_quarto.yml 中配置 Quarto 的构建过程
project:
  type: website
  pre-render:
    - pysym2md --output_file apilist.txt nbdev
  post-render:
    - llms_txt2ctx llms.txt --optional true --save_nbdev_fname llms-ctx-full.txt
    - llms_txt2ctx llms.txt --save_nbdev_fname llms-ctx.txt
  resources:
    - "*.txt"

请记住在您的 llms.txt 文件中手动添加一个指向生成的 apilist.txt 的链接。一旦您提交这些更改并重新构建您的文档，您的库就准备好与 LLM 进行更深入、更准确的对话了！

从示例中学习

研究别人如何实现我们正在做的事情通常很有用。fastcore 和 FastHTML 项目提供了很好的参考，您可以在 llmstxt.site 和 llmstxt.cloud 目录中找到更多示例。

要在一个地方查看所有必要的更改，这里有一个将 llms.txt 添加到现有 nbdev 项目的完整示例。

提供正确的上下文为 AI 辅助开发和探索您可能想深入了解的主题开辟了新的可能性。我们希望本指南能帮助您和您库的用户利用这些激动人心的新工具。