# 用户
欢迎阅读 Jupyter AI 的用户文档。
如果您有兴趣为 Jupyter AI 做出贡献，请参阅我们的 {doc}`贡献者指南 `。
如果您希望构建增强 Jupyter AI 的应用程序，请参阅 {doc}`开发者指南 `。
## 前提条件
您可以在任何能够运行支持的 Python 版本（从 3.8 到 3.12）的系统上运行 Jupyter AI，包括最新的 Windows、macOS 和 Linux 版本。
如果您使用 `conda`，可以通过运行以下命令在您的环境中安装 Python 3.12：
```
conda install python=3.12
```
`jupyter_ai` 包提供了 JupyterLab 中的实验室扩展和用户界面，依赖于 JupyterLab 4。如果无法在您的环境中升级到 JupyterLab 4，您应该安装 `jupyter_ai` v1.x 版本。更多详情请参阅“安装”部分。
:::{attention}
:name: jupyter-lab-3-end-of-maintenance
JupyterLab 3 已于 2024 年 5 月 15 日达到维护结束日期。因此，我们将不再将新功能向后移植到支持 JupyterLab 3 的 v1 分支。对于关键问题的修复仍将向后移植至 2024 年 12 月 31 日。如果您仍在使用 JupyterLab 3，我们强烈建议您**尽快升级到 JupyterLab 4**。更多信息请参阅 Jupyter 博客上的 [JupyterLab 3 维护结束](https://blog.jupyter.org/jupyterlab-3-end-of-maintenance-879778927db2)。
:::
您可以使用 `pip` 或 `conda` 安装 JupyterLab。
1. 通过 `pip`：
```
# 如果需要 JupyterLab 3，请将 4.0 更改为 3.0
pip install jupyterlab~=4.0
```
2. 通过 `conda`：
```
# 如果需要 JupyterLab 3，请将 4.0 更改为 3.0
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install jupyterlab~=4.0
```
您还可以在 Jupyter Notebook 7.2+ 中使用 Jupyter AI。要安装 Jupyter Notebook 7.2：
1. 通过 `pip`：
```
pip install notebook~=7.2
```
2. 通过 `conda`：
```
conda install notebook~=7.2
```
:::{note}
要在 Jupyter Notebook 中激活聊天界面，请点击“视图 > 左侧边栏 > 显示 Jupyter AI 聊天”。
:::
`jupyter_ai_magics` 包仅提供 IPython 魔法功能，不依赖于 JupyterLab 或 `jupyter_ai`。您可以在不安装 `jupyterlab` 或 `jupyter_ai` 的情况下安装 `jupyter_ai_magics`。如果您同时安装了 `jupyter_ai_magics` 和 `jupyter_ai`，您应该确保两者的版本相同，以避免错误。
Jupyter AI 内部使用 Pydantic v1，并且应该与 Pydantic 版本 1 或版本 2 兼容。为了兼容性，使用 Pydantic V2 的开发者应使用 `pydantic.v1` 包导入类。有关开发者如何使用 `v1` 以避免在代码中混合使用 v1 和 v2 类的建议，请参阅 [LangChain Pydantic 迁移计划](https://python.langchain.com/docs/guides/pydantic_compatibility)。
## 安装
### 通过 `pip` 安装
要安装 JupyterLab 扩展，您可以运行：
```
pip install jupyter-ai
```
您可能需要安装第三方包，例如，为了使用某些模型提供者和某些文件格式与 Jupyter AI。要处理所有支持的使用场景，您可以安装所有依赖项，这将使您能够访问 `jupyter-ai` 当前支持的所有模型。要安装所有依赖项，请运行以下命令，然后重新启动 JupyterLab：
```
pip install jupyter-ai[all]
```
`jupyter-ai` 的最新主要版本 v2 仅支持 JupyterLab 4。如果您需要支持 JupyterLab 3，您应该安装 `jupyter-ai` v1 版本：
```
pip install jupyter-ai~=1.0
```
如果您不使用 JupyterLab，并且只想安装 Jupyter AI 的 `%%ai` 魔法功能，您可以运行：
```
$ pip install jupyter-ai-magics
```
`jupyter-ai` 依赖于 `jupyter-ai-magics`，因此安装 `jupyter-ai` 会自动安装 `jupyter-ai-magics`。
### 通过 `pip` 或 `conda` 在 Conda 环境中安装（推荐）
我们强烈建议在独立的 Conda 环境中安装 JupyterLab 和 Jupyter AI，以避免覆盖您现有 Python 环境中的 Python 包。
首先，安装 [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) 并创建一个使用 Python 3.12 的环境：
$ conda create -n jupyter-ai python=3.12
$ conda activate jupyter-ai
然后，使用 `conda` 在此 Conda 环境中安装 JupyterLab 和 Jupyter AI。
$ conda install -c conda-forge jupyter-ai # 或者，
$ conda install conda-forge::jupyter-ai
在启动带有 Jupyter AI 的 JupyterLab 时，请确保首先激活 Conda 环境：
```
conda activate jupyter-ai
jupyter lab
```
## 卸载
如果您使用 `pip` 安装了 Jupyter AI，要移除扩展，请运行：
$ pip uninstall jupyter-ai
或者
$ pip uninstall jupyter-ai-magics
如果您使用 `conda` 安装了 Jupyter AI，您可以通过运行以下命令移除它：
$ conda remove jupyter-ai
或者
$ conda remove jupyter-ai-magics
Jupyter AI 支持多种模型提供商和模型。要使用特定的提供商与 Jupyter AI，您必须安装其 Python 包并在您的环境中或聊天界面中设置其 API 密钥（或其他凭证）。
Jupyter AI 支持以下模型提供商：
| 提供商 | 提供商 ID | 环境变量 | Python 包 |
|------------------------------|----------------------|----------------------------|-------------------------------------------|
| AI21 | `ai21` | `AI21_API_KEY` | `ai21` |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `langchain-anthropic` |
| Anthropic (聊天) | `anthropic-chat` | `ANTHROPIC_API_KEY` | `langchain-anthropic` |
| Bedrock | `bedrock` | N/A | `langchain-aws` |
| Bedrock (聊天) | `bedrock-chat` | N/A | `langchain-aws` |
| Bedrock (自定义/预置) | `bedrock-custom` | N/A | `langchain-aws` |
| Cohere | `cohere` | `COHERE_API_KEY` | `langchain-cohere` |
| ERNIE-Bot | `qianfan` | `QIANFAN_AK`, `QIANFAN_SK` | `qianfan` |
| Gemini | `gemini` | `GOOGLE_API_KEY` | `langchain-google-genai` |
| GPT4All | `gpt4all` | N/A | `gpt4all` |
| Hugging Face Hub | `huggingface_hub` | `HUGGINGFACEHUB_API_TOKEN` | `huggingface_hub`, `ipywidgets`, `pillow` |
| MistralAI | `mistralai` | `MISTRAL_API_KEY` | `langchain-mistralai` |
| NVIDIA | `nvidia-chat` | `NVIDIA_API_KEY` | `langchain_nvidia_ai_endpoints` |
| OpenAI | `openai` | `OPENAI_API_KEY` | `langchain-openai` |
| OpenAI (聊天) | `openai-chat` | `OPENAI_API_KEY` | `langchain-openai` |
| SageMaker 端点 | `sagemaker-endpoint` | N/A | `langchain-aws` |
上述环境变量名称也是设置聊天界面时使用的设置键名称。如果为某个提供商列出了多个变量，则**所有**变量都必须指定。
要使用 Bedrock 模型，您需要访问 Bedrock 服务，并且需要通过 [boto3](https://github.com/boto/boto3) 进行身份验证。更多信息请参见 [Amazon Bedrock 主页](https://aws.amazon.com/bedrock/)。
您需要 `pillow` Python 包来使用 Hugging Face Hub 的文本到图像模型。
您可以在 [https://huggingface.co/models](https://huggingface.co/models) 找到 Hugging Face 的模型列表。
要使用 NVIDIA 模型，请在 [NVIDIA NGC 服务](https://catalog.ngc.nvidia.com/) 上创建一个免费账户，该服务托管 AI 解决方案目录、容器、模型等。导航到目录 > [AI 基础模型](https://catalog.ngc.nvidia.com/ai-foundation-models)，并选择一个带有 API 端点的模型。点击模型详情页上的“API”，然后点击“生成密钥”。保存此密钥，并将其设置为环境变量 `NVIDIA_API_KEY` 以访问任何模型端点。
SageMaker 端点名称是在您部署模型时创建的。更多信息请参见 SageMaker 文档中的 ["创建您的端点并部署您的模型"](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-deployment.html)。
要使用 SageMaker 的模型，您需要通过 [boto3](https://github.com/boto/boto3) 进行身份验证。
例如，要使用 OpenAI 模型，请使用聊天界面设置面板选择 OpenAI 语言模型：
然后，在“API 密钥”部分输入您的 API 密钥。
:::{attention}
:name: open-ai-cost
模型提供商可能会向用户收取 API 使用费用。Jupyter AI 用户需对其发起的 API 请求所产生的所有费用负责。在使用 Jupyter AI 提交请求之前，请查看您的模型提供商的定价信息。
:::
## 聊天界面
开始使用 Jupyter AI 的最简单方法是使用聊天界面。
:::{attention}
:name: open-ai-privacy-cost
聊天界面将数据发送给由第三方托管的生成式AI模型。请查看您的模型提供商的隐私政策，以了解它可能如何使用您发送给它的数据。查看其定价模型，以便您了解在使用聊天界面时的付款义务。
:::
启动JupyterLab后，点击左侧边栏中的新“聊天”图标以打开聊天界面。如果您愿意，可以右键点击面板图标并将其移动到另一侧。
首次打开聊天界面时，Jupyter AI会询问您希望使用哪种模型作为语言模型和嵌入模型。一旦您做出选择，界面可能会显示一个或多个设置键的文本框。
:::{admonition} 语言模型和嵌入模型
:class: tip
:name: language-models-and-embedding-models
用户可以选择一个语言模型，并可选地选择一个嵌入模型。您应该选择其中一个，以便能够使用聊天界面的全部功能。
**语言模型** 在聊天面板中响应用户的留言。它接受一个提示并生成一个响应。语言模型通常是*预训练*的；它们可以直接使用，但它们的训练集存在偏见和不完整，用户在使用聊天界面时需要意识到这些偏见。
**嵌入模型** 在[学习和询问本地数据](#learning-about-local-data)时使用。这些模型可以将您的数据（包括文档和源代码文件）转换为向量，这些向量可以帮助Jupyter AI构建提示以供语言模型使用。
您的语言模型和嵌入模型不需要由同一家供应商提供，但您需要为每个使用的模型提供商提供身份验证凭据。
:::
在使用聊天界面之前，您需要为您选择的模型提供商提供API密钥。将您的密钥粘贴或输入到提供的框中。
一旦设置了所有必要的密钥，点击Jupyter AI侧边栏左上角的“返回”（左箭头）按钮。聊天界面现在出现，并附带可用的`/`（斜杠）命令的帮助菜单，您可以使用底部的消息框提问。
您可以从默认模板自定义聊天界面的模板。步骤如下：
1. 在当前目录中创建一个新的`config.py`文件，内容为您希望在帮助消息中看到的内容，通过编辑以下模板：
```
c.AiExtension.help_message_template = """
Sup. I'm {persona_name}. 这是一个自定义的帮助消息。
以下是您可以使用的斜杠命令。用不用...我不在乎。
{slash_commands_list}
""".strip()
```
2. 使用以下命令启动JupyterLab：
```
jupyter lab --config=config.py
```
新的帮助消息将代替默认消息使用，如下所示
要撰写消息，请在聊天界面底部的文本框中输入内容，然后按ENTER发送。您可以按SHIFT+ENTER添加新行。（这些是默认的键绑定；您可以在聊天设置面板中更改它们。）一旦发送消息，您应该会看到Jupyternaut（Jupyter AI聊天机器人）的响应。
聊天后端会记住您对话中的最后两次交流，并将它们传递给语言模型。您可以提出后续问题，而无需重复之前的对话信息。以下是一个带有后续问题的聊天对话示例：
#### 初始问题
#### 后续问题
### Amazon Bedrock 使用
Jupyter AI 支持在 AWS 上使用托管于 [Amazon Bedrock](https://aws.amazon.com/bedrock/) 的语言模型。首先，请确保您已通过 `boto3` SDK 使用存储在 `default` 配置文件中的凭证进行 AWS 身份验证。有关如何进行此操作的指导，请参阅 [`boto3` 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)。
如需更详细的流程，请参阅 [使用 Amazon Bedrock 与 Jupyter AI](bedrock.md)。
Bedrock 支持多家语言模型提供商，如 AI21 Labs、Amazon、Anthropic、Cohere、Meta 和 Mistral AI。要使用任何受支持提供商的基础模型，请确保在 Amazon Bedrock 中启用它们，这可以通过 AWS 控制台完成。如果您打算在文档上使用检索增强生成（RAG），还应在 Bedrock 中选择嵌入模型以及语言补全模型。
现在，您可以从聊天界面中的 `Completion model` 下拉菜单中选择一个 Bedrock 模型。如果将使用 RAG，则同样从 Bedrock 模型中选择一个嵌入模型。以下是这些选择的示例：
如果您的提供商需要 API 密钥，请在相应提供商的输入框中输入。确保点击 `Save Changes` 以确保输入内容已保存。
Bedrock 还允许从头开始训练自定义模型或从基础模型进行微调。Jupyter AI 支持在聊天面板中使用其 `arn`（Amazon 资源名称）调用自定义模型。界面如下所示：
如需详细流程，请参阅 [使用 Amazon Bedrock 与 Jupyter AI](bedrock.md)。
### SageMaker 端点使用
Jupyter AI 支持使用 JSON 模式的 SageMaker 端点托管的语言模型。第一步是通过 `boto3` SDK 进行 AWS 身份验证，并将凭证存储在 `default` 配置文件中。有关如何进行此操作的指导，请参阅 [`boto3` 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)。
在设置面板中选择 SageMaker 提供商时，您将看到以下界面：
“Language model”下的每个附加字段都是必需的。这些字段应包含以下数据：
- **Endpoint name**: 您的端点名称。可以从以下 URL 在 AWS 控制台中检索：`https://.console.aws.amazon.com/sagemaker/home?region=#/endpoints`。
- **Region name**: SageMaker 端点所在的 AWS 区域，例如 `us-west-2`。
- **Request schema**: 端点期望的 JSON 对象，提示将替换为与字符串字面量 `""` 匹配的任何值。在此示例中，请求模式 `{"text_inputs":""}` 生成一个 JSON 对象，提示存储在 `text_inputs` 键下。
- **Response path**: 一个 [JSONPath](https://goessner.net/articles/JsonPath/index.html) 字符串，用于从端点的 JSON 响应中检索语言模型的输出。在此示例中，端点返回一个具有模式 `{"generated_texts":["