textlong 0.3.6

A framework designed to produce long-texts with GPT or other large language models.

🦜🦜🦜 textlong

textlong 的目标是基于大语言模型提供结构化的长文本生成能力。

注意：以下文字全部使用textlong自动生成：

《textlong 使用指南》

1 环境准备

1.1 使用 dotenv 管理环境变量

dotenv 是一个在开发中常用的工具，它可以帮助我们管理项目中的环境变量。通过使用 dotenv，我们可以将敏感信息（如 API 密钥）与代码分离，从而避免在代码库中直接暴露这些信息。Python 中的 dotenv 包可以通过读取.env文件来加载环境变量。

安装 python-dotenv 包非常简单，你可以通过 pip 命令来完成安装：

pip install python-dotenv

创建和配置.env文件，你需要在你项目的根目录下创建一个名为.env的文件（注意，文件名以点开始）。在这个文件中，你可以定义你的环境变量，例如：

ZHIPUAI_API_KEY="你的智谱AI API密钥"
TEXTLONG_FOLDER="你的项目目录"

在 Python 代码中，你可以使用以下代码片段来加载.env文件中的环境变量：

from dotenv import load_dotenv, find_dotenv
load_dotenv(find_dotenv(), override=True)

接下来，你可以通过os.environ来访问这些环境变量：

import os
api_key = os.environ.get('ZHIPUAI_API_KEY')

对于大语言模型的申请，你可以选择申请美国公司 OpenAI、Claude 等提供的大语言模型，或者选择中国的智谱 AI 等大语言模型服务。申请完成后，你会获得一个 API_KEY，这是你调用相应服务的凭证。

获得 API_KEY 后，你需要将其配置到之前创建的.env文件中，这样在代码中就可以安全地引用这个密钥了。

1.2 申请大语言模型

当你决定申请大语言模型服务时，可以选择美国公司如 OpenAI 或 Claude 提供的服务，也可以选择中国的智谱 AI 等国内服务。这些服务通常都会提供详细的申请流程指引。申请过程中，你需要填写相关信息，并按照指引完成相应的步骤。成功申请后，你会获得一个 API_KEY，这是你调用这些大语言模型服务的唯一凭证。

获得 API_KEY 后，为了确保其安全性和便捷性，你应该将其配置到项目根目录下的.env文件中。这样，你的代码在需要引用这个密钥时，可以通过以下方式轻松获取：

import os
api_key = os.environ.get('YOUR_API_KEY_NAME')

这里的YOUR_API_KEY_NAME应该与你在.env文件中定义的环境变量名称一致。这种方式不仅能保护你的敏感信息，还能让你的代码更加整洁、易于管理。

2 textlong 的安装与加载

2.1 安装 textlong 包

在 Python 中安装 textlong 包非常简单，只需要使用 pip 命令即可。以下是一个安装 textlong 包的示例命令，它会尝试安装最新版本的 textlong：

pip install textlong

为了确保安装的是最新版本，可以在命令中添加--upgrade选项，如下：

pip install --upgrade textlong

执行上述命令时，请确保你的 pip 工具是最新版本，以避免安装过程中可能出现的兼容性问题。

如果你正在使用虚拟环境，确保你已经激活该环境，然后再运行上述 pip 命令，这样 textlong 包将被安装到虚拟环境中，而不会影响全局 Python 环境。

如果需要指定安装的版本，可以在 pip 命令中指定版本号，例如：

pip install textlong==1.2.3

这里1.2.3是假设的一个版本号，你应该根据需要替换成你想要安装的确切版本。

3 使用 Project 创作长文

3.1 在 jupyter 环境中使用 textlong

安装 JupyterLab

在使用 textlong 之前，首先需要确保你的环境中安装了 JupyterLab。JupyterLab 是一个交互式的开发环境，非常适合进行数据分析和机器学习项目。你可以通过以下命令安装 JupyterLab：

pip install jupyterlab

安装完成后，可以通过运行以下命令来启动 JupyterLab：

jupyter-lab

建立笔记

启动 JupyterLab 后，你将看到一个 Web 界面。点击页面右上角的New按钮，选择Python 3来创建一个新的笔记。

导入 textlong 包

在新的笔记中，首先需要导入 textlong 包。在进行导入之前，请确保已经按照前面的步骤正确安装了 textlong 包。以下是如何在 Jupyter 笔记中导入 textlong 包的示例：

首先，加载你的环境变量，这样你就可以安全地访问 API 密钥：

from dotenv import load_dotenv, find_dotenv
load_dotenv(find_dotenv(), override=True)

接下来，导入 textlong 包和所需的模型：

from textlong import Project
from langchain_zhipu import ChatZhipuAI

现在，你可以初始化一个 Project 对象，如下所示：

p = Project(ChatZhipuAI(model="glm-4"), project_id="project")
p

这里project_id是你为 textlong 项目指定的唯一标识符。确保你使用的是正确的 API 模型名称和项目 ID。

通过上述步骤，你就可以在 JupyterLab 环境中使用 textlong 包来创作长文了。

3.2 创作提纲

在创作长篇文章时，使用 textlong 的提纲功能可以帮助你更好地组织和规划文章结构。以下是如何使用 textlong 创作提纲的详细步骤。

首先，你需要明确文章的主题、大纲和关键要素。在这个例子中，我们要创作的是一部 500 字的修仙小说，标题为《我修了个假仙》，主角是夏小兰，男一号是周成，每个章节都将以意外和打脸的线索推动情节。

接下来，使用 textlong 的from_idea方法来创建提纲。该方法接收三个参数：提纲文件的路径、文章创作的任务描述以及 prompt_id。以下是一个代码示例：

task = "请帮我创作500字的修仙小说，标题为《我修了个假仙》，主角是夏小兰，男一号是周成，每一个章节都适用意外、打脸的线索推动。"
p.from_idea("提纲.md", task, prompt_id="OUTLINE")

在上面的代码中，"提纲.md"是生成的提纲文件的存储路径，task 是对文章创作任务的描述，prompt_id 用于标识这个提纲。

当你运行上述代码后，textlong 会根据你的任务描述自动生成一份提纲。提纲将包括小说的章节划分和每个章节的关键情节。你可以根据这个提纲来进行文章的扩写。

在提纲的基础上，你可以使用 textlong 的 Project 对象来逐步完成文章的创作。通过调用 Project 对象的相应方法，你可以让 AI 帮助你完成每个章节的细节描写，从而实现整篇小说的创作。

总之，使用 textlong 创作提纲可以大大提高你的写作效率，使你能够更加专注地构思情节和塑造角色，让创作过程变得更加轻松愉快。

示范结果如下：

# 《我修了个假仙》

## 第一章：星辰之女的觉醒

<OUTLINE>
夏小兰一直被认为拥有神秘力量，却在一次意外中被揭露出她的能力并不如外界传言那般强大，实际上她修了个“假仙”。这次觉醒让她在村中受尽白眼，决心踏上寻找真正修仙之道的旅程。

扩写要求：

- 预估字数：150
- 创意要点：意外揭露，能力不足，决心追求真相
- 创作思路：通过主角的失落和觉醒，引出后续成长和冒险
- 涉及实体名称：夏小兰，星辰之女

</OUTLINE>

...

3.3 文章扩写

基于提纲进行文章扩写是 textlong 的核心功能之一。它能够帮助作者根据已有的提纲框架，快速生成详细的文章内容。以下是如何使用 textlong 进行文章扩写的具体步骤。

首先，你需要有一个通过 textlong 生成的提纲文件，比如在我们的例子中，这个文件是“提纲.md”。然后，利用 textlong 的from_outline方法，你可以根据这个提纲文件生成文章的初稿。

基本的使用方法如上面的代码示例所示，你需要指定输出的文件名和输入的提纲文件名。例如：

p.from_outline(
    output_file="我修了个假仙人.md",
    input_file="提纲.md"
)

通过运行上述代码，textlong 将根据“提纲.md”中的结构，生成一篇名为“我修了个假仙人.md”的文章初稿。

然而，你可能希望对生成的文章进行微调，以更好地符合你的创作风格或文章需求。为此，你可以像下面这样调整from_outline方法的参数：

p.from_outline(
    output_file="我修了个假仙人.md",
    input_file="提纲.md",
    task="多使用人物细节、对话描写、打斗描写，减少抽象叙事"
)

在这个调整后的代码中，我们添加了一个额外的参数task，用于指导 AI 在生成文章时要特别关注的方面。这样，生成的文章将包含更多的人物细节、对话和打斗描写，同时减少抽象的叙述。

在使用from_outline方法时，你还可以根据需要调整其他参数，如word_count来控制生成的文章字数，或者temperature来调整生成内容的创意程度。

总之，通过这些步骤，你不仅能够基于提纲快速生成文章内容，还能够通过调整参数来优化和个性化生成的文章，使得最终的成品更加符合你的预期和创作要求。

示范结果如下：

# 《我修了个假仙》

## 第一章：星辰之女的觉醒

夏小兰，一直被村民视为拥有神秘力量的星辰之女。然而，在那次意外中，她的真实能力被揭穿，原来她修了个“假仙”。村中的嘲笑与白眼，让她痛不欲生。夏小兰站在村口，紧握双拳，眼中闪过坚定：“我一定要找到真正的修仙之道，证明给所有人看！”

那天，阳光透过云层洒在她的脸上，仿佛预示着她即将踏上的艰难旅程。夏小兰迈开坚定的步伐，离开这个让她充满失落的地方，去寻找属于自己的真相。

...

3.4 引用素材管理

在创作长篇小说时，一个重要环节是生成和整理素材。textlong 工具提供了from_idea方法，可以帮助你快速生成特定主题的素材。比如，你可以通过以下代码生成关于小说人物的设定：

task = "我要写一个修仙小说，主角是夏小兰，男一号是周成，请帮我设想一下这两个人的出身，要非常魔幻。"
p.from_idea("人物设定.md", task)

这段代码会根据你的要求，生成一份包含夏小兰和周成详细背景设定的文件“人物设定.md”。接下来，你可以使用这些素材来丰富你的文章。

当你想要在文章中使用这些素材时，可以通过from_outline方法中的kg_files参数来引用它们。如下示例：

p.from_outline(
    output_file="我修了个假仙人.md",
    input_file="提纲.md",
    task="多使用人物细节、对话描写、打斗描写，减少抽象叙事",
    kg_files=["人物设定.md"]
)

在这个例子中，kg_files参数指向了我们之前生成的“人物设定.md”。这样，textlong 在生成文章时，会自动参考这些素材，使得文章中的人物形象更加丰满，故事更加生动。

通过这种方式，你可以在创作过程中有效地管理素材，并确保它们被合理地融入文章中。这不仅提高了写作效率，还能使文章内容更加连贯和具有深度。

生成的人物设定可以作为素材，被引用到文章的相应部分，使故事更加引人入胜。

当素材准备好后，你可以将其整合到文章中，利用 textlong 的引用功能进行重新生成，确保整个故事的连贯性和统一性。