Obsidian 插件：【Readme】Copilot auto completion

概述

使用 ChatGPT API，为 Obsidian 添加一个高度可配置的类似副驾驶的自动补全功能。

Readme(翻译）

下面是 copilot-auto-completion 插件的自述翻译

Obsidian 中的类似 Copilot 的自动补全

该插件为 Obsidian 添加了类似 Copilot 的自动补全功能。

它使用 OpenAI API 或 Azure OpenAi API 根据光标前后的 n 个字符生成文本。

它会在光标旁边显示透明文本的建议补全。

然后，您可以按 Tab 键插入建议。此外，您还可以按 Escape 键或移动光标来忽略建议。

用法

当你在写作时，插件会监视光标前的文本是否与任何触发词或正则表达式匹配。

如果匹配成功，它将排队一个预测请求。

如果你移动光标、改变文档或按下 Escape 键，插件将取消预测请求。

为了防止过多的 API 调用，预测请求将被排队一段时间。

一旦预测请求被发出，插件将以透明文本显示建议。

你可以通过按 Tab 键或使用 “Obsidian Copilot: Accept” 快速操作来接受它。

如果你按下 Escape 键、移动光标或改变文档，建议将被取消。

有时，你可能想在文档的特定位置强制进行预测请求。

理论上，你可以添加一个总是匹配的触发规则，但这可能很耗费资源。

相反，你可以使用 “Obsidian Copilot: Predict” 快速操作。

插件将直接发出预测请求并显示建议。

如果你正在处理一个隐私敏感的文档，可能不希望与 API 提供商共享其内容。

为了防止这种情况，你可以暂时禁用插件。

最简单的方法是使用其中一个快速操作。

打开命令面板（在 Mac 上是 CMD + P，在 Windows 上是 CTRL + P），然后搜索 “Obsidian Copilot: Disable”。这个操作将使插件处于禁用状态。

在这个状态下，插件将忽略所有的触发器，并且不会将任何文本发送给 API 提供商。

即使你关闭并重新打开 Obsidian，插件也会保持在这个状态。

当你想要再次启用插件时，可以使用 “Obsidian Copilot: Enable” 快速操作。

安装

安装插件后，您需要配置您的 API 提供商。

您可以按照以下步骤进行操作：

1. 进入插件设置。
2. 确保您已安装并在“社区插件”设置中启用了此插件。
3. 进入“Obsidian Copilot”设置。
4. 选择您的 API 提供商。
5. 如果您选择了 OpenAI API，则必须提供您的 API 密钥。
6. 如果您选择了 Azure OpenAI API，则必须提供您的 API 密钥和终端。
7. 点击测试连接按钮以验证插件是否能够连接到 API 提供商。如果测试失败，请检查您的 API 密钥和终端。
8. 关闭设置窗口。
9. 您现在可以开始使用该插件了。

它是如何工作的？

模型

预测任务被定义为一个掩码替换任务。

通过使用提示工程，我们可以创建一个 Chat-LLM 模型来执行这个任务。

为此，我们给模型提供以下系统指令：

你的任务是预测应该在<mask/>位置写入的最合逻辑的文本。
你的答案可以是代码、一个单词或多个句子。
你的答案必须与已有文本的语言相同。
你的回答必须具有以下格式：
THOUGHT: 这里你解释一下你认为<mask/>位置可能是什么的推理过程
ANSWER: 这里你写下应该在<mask/>位置的文本

然后，我们以 <truncated_text_before_cursor> <mask/> <truncated_text_after_cursor> 的格式向模型提供（截断的）光标前后的文本。

例如，对于上面示例中 Attention 公式的用户消息，模型的输入将是：

加权平均（序列）元素，权重根据输入查询和元素键动态计算。

注意力权重$a_i$的计算如下：
$$
<mask/>
$$

在这个公式中，我们有以下组成部分：
- 值：对于每个元素，我们有一个要进行平均的元素特征向量。
- 分数函数$f_{score}(key, query)$：使用查询和键来计算每个值的权重。（通常是一个简单的相似度度量或MLP。）
- 注意力权重$\alpha_i$：在值$i$上放置的注意力的数量。

然后，模型会回复类似于：

THOUGHT: </mask>位于一个数学块中。掩码之前的文本解释了注意力权重的计算。根据文本，我的答案应该是使用分数函数计算注意力权重的公式。
ANSWER: \alpha_i = \frac{\exp(f_{score}(key_i, query))}{\sum_j \exp(f_{score}(key_j, query))}

思考部分帮助模型推理任务，并将注意机制集中在文本的相关部分。

然而，思考部分对用户来说并不是很有用。

因此，我们删除了这部分。结果，建议只包含在 ANSWER: 部分之后生成的文本。

正如你在上面的示例中所看到的，模型只能访问当前文档中的文本。

这样可以防止模型泄露可能涉及隐私的其他文档中的信息。

上述的模型设置已经运行得相当不错，但是通过使用上下文感知的少样本示例可以进一步改进。

这里的关键思想是我们期望在文档的特定位置得到特定类型的答案。

例如：

• 在数学块中，我们期望得到 LaTeX 公式。
• 在代码块中，我们期望得到与代码块相同语言的代码。
• 在列表中，我们期望得到一个新的列表项。
• 在标题中，我们期望得到代表段落内容的新标题。
• 在段落中，我们期望得到与周围文本一致的新句子。
• 等等。

你可能还可以想到许多其他的例子和规则。

因此，系统提示可能会变得长而复杂。

相反，通过给模型一些示例的输入和输出对，可以更容易地避免这种情况。

这些对隐含地向模型展示了在给定上下文中你期望的响应。

例如，我们在数学块中给模型以下示例。

输入：

# 样本均值
样本均值，有时也称为平均值，定义如下：

$$
sample_mean(x) = \frac{1}{n} \sum_i^n x_i
$$
平均值具有以下特性：50%的加权值将在其上方和下方。这种加权特性使得它对异常值更敏感，而中位数则不然。
### 插件设计
该插件的设计旨在最小化API调用的次数。
它通过使用智能排队和触发检测系统来实现这一目标。
这个系统可能会变得非常复杂，因此它使用了一个[状态机](https://refactoring.guru/design-patterns/state)进行设计。
在Obsidian窗口的右下角，您可以看到插件的当前状态。
插件始终处于以下状态之一：
- **空闲**：插件已启用，等待触发。
- **排队**：插件已检测到触发，并正在等待触发延迟到期后进入预测状态。
- **预测**：插件向API提供者请求预测。
- **建议**：插件显示预测建议，并等待用户接受或拒绝。
- **禁用**：插件已禁用，防止其对任何触发作出反应。

排队状态是最重要的状态，用于最小化API调用的次数，因为它防止插件在预测状态下进行不必要的API调用。这一点很重要，因为即使您不使用其中的建议，API提供者也会对所有API调用进行计费。
您可以通过配置插件保持排队的时间来减少这些成本。
增加此延迟将减少API调用的次数，但也会使插件的响应速度变慢。
因此，您应该找到适合自己的这两个因素之间的平衡点。

以下图表显示了状态之间的关系和转换：
![states](assets/state_diagram.jpg)
个性化和设置
该插件被设计为高度可定制的。
您可以自定义以下插件的方面。
### 触发器
该插件具有默认的触发器，例如：
- 句子结束：`.` `!` `?`
- 行结束：`\n`
- 列表或任务项。
- 等等。

如果您喜欢不同的触发器，您可以编辑或删除默认触发器，或者添加您自己的触发器。
要做到这一点，请转到设置和触发器部分。
如果您按下“+”按钮，您可以添加一个新的触发器。
您必须决定每个触发器是一个字符串还是一个正则表达式触发器。
如果选择字符串，插件将检查前缀是否以此特定字符串结尾。
如果选择正则表达式，插件将检查前缀是否与正则表达式匹配。
不要忘记为正则表达式触发器添加行结束符号（`$`）。否则，您可能会在前缀的中间匹配。
此外，请注意，过于触发敏感的触发器可能会导致更多的API调用，从而增加成本。
### 触发延迟
触发延迟是插件在进入预测状态之前保持在排队状态的时间量。
这个延迟可以防止插件在用户继续输入时自动取消预测请求，从而减少API调用次数。
您可以在设置中配置此延迟。
增加此延迟将减少API调用次数，但也会使插件的响应速度降低。
因此，您应该找到适合自己的这两个因素之间的平衡点。
### 模型选项
LLM模型还有一些可以调整的超参数。
例如，您可以自由更改以下参数：
- `temperature`：控制随机性。较低的温度会导致更多重复和确定性的回答。较高的温度会导致更多意外或创造性的回答。
- `top_p`：与温度类似，降低Top P会将模型的令牌选择限制在更可能的令牌上。增加Top P会扩大模型的令牌选择范围，包括更低概率的令牌。
- `max_tokens`：模型允许生成的最大令牌数。这包括答案之前的思路链令牌。
- `presence_penalty`：减少重复出现在文本中的任何令牌的机会。这增加了在回答中引入新主题的可能性。
- `frequency_penalty`：根据在文本中出现的频率，按比例减少重复令牌的机会。这降低了在回答中重复相同文本的可能性。

这些参数允许您自定义模型的创造力和可靠性。
请随意尝试这些参数，找到最适合您的最佳设置。
### 预处理
在文本发送给API提供者之前，插件会进行一些预处理。
这通常涉及删除一些与API提供者无关的文本。
这里最重要的是要确定你想在预测请求中包含的前缀和后缀的字符数。
这些设置将把前缀截断为最后的`n`个字符，并将后缀截断为前面的`m`个字符。
特别是对于大型文档，这可以显著减少推理时间和成本。
然而，如果将这些值设置得太低，模型可能没有足够的上下文来生成一个好的回答。
因此，你应该找到适合你的这两个因素之间的平衡点。
### 高级配置
对于高级用户，我们还提供了自定义插件的提示工程方面的选项。
这些设置默认情况下是隐藏的，但您可以通过启用高级模式设置来使它们可见。
请随意尝试这些设置，找到最适合您的设置。
如果您弄乱了设置，您可以始终使用工厂重置按钮将其重置为默认值。
请注意，这将重置所有设置为默认值。
因此，请确保在想要保留设置的情况下备份您的设置。
#### 自定义系统提示
[model](#model) 部分显示了默认的系统提示。
这个提示是完全可定制的。
请随意尝试不同的提示设置，找到最适合您的设置。
但是，请注意您必须使其与以下设置保持一致：
- [少量示例](#customize-the-few-shot-examples)
- 链式思维删除正则表达式：该正则表达式从响应中删除所有与答案无关的文本。如果没有正确执行此操作，可能会在建议中得到意外的文本。
- 用户消息模板：该模板用于生成在建议中显示的用户消息。它确定了前缀、掩码和后缀如何组合成一个单一的消息。

![system_prompt](assets/system_message_settings.jpg)
自定义少样本示例

在[模型](#model)部分，我们展示了如何利用少样本示例来改进模型的预测结果。
这些示例是完全可定制的。
您可以通过点击“+”按钮（红色矩形）来添加示例。
您可以通过点击“x”按钮（蓝色矩形）来删除示例。
一个示例由三个部分组成：
- **上下文**（黄色矩形）：这是示例应该使用的上下文。插件使用这个上下文来确定何时使用这个示例。如果光标不在这个上下文中，示例将不会被使用。
- **人类消息**：这是我们想要给模型的输入。这是一个包含`<mask/>`之前和之后文本的示例文档。
- **辅助消息**：这是一个适当回应的示例答案。这个答案应该与系统提示和思路链的移除正则表达式一致。

![few_shot_examples](assets/few_shot_example_settings.jpg)
## 本地开发
要在本地开发插件，可以按照以下步骤进行操作：

1. 进入你的（开发中的）Obsidian vault。
2. 找到包含所有配置文件的dotfiles文件夹。通常命名为`.obsidian`。
3. 进入插件文件夹。通常命名为`plugins`。如果你没有安装任何插件，这个文件夹可能不存在。
4. 使用以下命令在此处克隆项目：`git clone https://github.com/j0rd1smit/obsidian-copilot`。
5. 使用以下命令进入新创建的obsidian-copilot文件夹：`cd obsidian-copilot`。
6. 使用以下命令安装依赖项：`npm install`。
7. 使用以下命令运行构建脚本：`npm run dev`。这将监视文件并在您进行更改时自动重新构建插件。
8. 重新启动Obsidian以加载插件。您还可以使用“重新加载应用程序而不保存”操作重新加载Obsidian应用程序而无需关闭它。
9. 进入社区插件并启用obsidian-copilot。
10. 进入obsidian-copilot设置并添加所需的密钥。

现在，您可以对插件进行更改，并在Obsidian应用程序中看到这些更改的反映。
如果您的更改对他人有帮助，请随时提交拉取请求。
## 免责声明
该插件作为与API提供商的连接。
我们不会访问或保留您的数据，但API提供商可能会这样做。
因此，重要的是审查和理解他们的条款和条件以及隐私政策。
请注意，我们对您向API提供商提供的任何信息不承担责任。
您可以根据您的文档内容自行决定启用或禁用插件。
然而，这样做是您自己的责任。
在与API提供商共享敏感信息（如密码或个人数据）时，请谨慎行事。