AI 伙伴应用（基于 AI 入门模板）

在线演示

加入我们的社区 Discord：AI Stack 开发者

这是一个用于创建和托管 AI 伙伴的教程栈，你可以在浏览器上与它们聊天，也可以通过短信进行文本交流。它允许你自定义伙伴的性格和背景故事，并使用向量数据库进行相似性搜索来检索相关信息并生成提示，从而使对话更加深入。此外，它还会将对话内容保存在队列中，并将其纳入提示中，以实现一定的对话记忆功能。

目前，该栈包含了基于 ChatGPT 和 Vicuna 的伙伴，这些模型都托管在 Replicate 上。

这些伙伴有多种潜在的应用场景——浪漫关系（AI 女朋友/男朋友）、友谊、娱乐、辅导等。你可以通过编写背景故事以及选择合适的模型，引导你的伙伴朝向理想的使用场景发展。

注意 本项目纯粹旨在为开发者提供一个教程和入门框架，帮助那些对聊天机器人构建方式感兴趣的人了解其工作原理。如果你希望了解生产级开源平台的样子，请查看 Steamship；如果你想了解领先的 AI 聊天平台，可以访问 Character.ai。

概述

• 💻 技术栈
• 🧠 快速入门
• 🚀 它是如何工作的？
• 👤 添加/修改角色
• 👩‍💻 如何为本仓库贡献代码
• 🐍 Python 支持
• 💽 将你的伙伴导出到 Character.ai

技术栈

该栈基于 AI 入门栈：

• 身份验证：Clerk
• 应用逻辑：Next.js
• 向量数据库：Pinecone / Supabase pgvector
• LLM 编排：Langchain.js
• 文本模型：OpenAI、Replicate (Vicuna13b)
• 文本流式传输：ai sdk
• 对话历史：Upstash
• 部署：Fly
• 与伙伴的文本交互：Twilio

快速入门

以下步骤将帮助你快速搭建一个功能齐全的本地部署环境，并运行四个可供聊天的 AI 伙伴。请注意，基于 Vicuna 运行的伙伴（Rosie 和 Lucky）由于尚未解决冷启动问题，响应速度会较慢，因此可能需要稍作等待 :)

1. 分支并克隆仓库

首先将仓库 fork 到你的 GitHub 账号，然后运行以下命令克隆仓库：

git clone git@github.com:[YOUR_GITHUB_ACCOUNT_NAME]/companion-app.git

或者，你也可以通过 GitHub Codespaces 快速启动应用：点击“Code” -> “Codespaces” -> “+”

如果你选择使用 Codespaces，npm 依赖项将会自动安装，随后你可以直接进入第 3 步。

2. 安装依赖项

cd companion-app
npm install

3. 填写密钥

cp .env.local.example .env.local

以下提到的密钥需要复制到 .env.local 文件中：

a. Clerk 密钥

前往 https://dashboard.clerk.com/ -> “添加应用” -> 填写应用名称并选择用户登录方式 -> 创建应用
现在您应该能在界面上看到 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY

如果您希望在后续步骤中通过短信与 AI 伙伴互动，还应在左侧导航栏的“用户与认证” -> “电子邮件、电话、用户名”下启用“电话号码”：

b. OpenAI API 密钥

如果您使用 OpenAI 作为语言模型，请访问 https://platform.openai.com/account/api-keys 获取您的 OpenAI API 密钥。

c. Replicate API 密钥

如果您使用 Vicuna 作为语言模型，请访问 https://replicate.com/account/api-tokens 获取您的 Replicate API 密钥。

❗ 注意: 默认情况下，此模板使用 Pinecone 作为向量数据库，但您可以通过取消注释 .env.local 中的 VECTOR_DB=supabase 来轻松切换到 Supabase pgvector。这意味着您只需填写 Pinecone API 密钥或 Supabase API 密钥中的一个。

d. Pinecone API 密钥

• 访问 https://app.pinecone.io/ 并点击“创建索引”以创建 Pinecone 索引
• 为索引命名（这将成为环境变量 PINECONE_INDEX）
• 将维度设置为 1536
• 索引成功创建后，点击左侧导航栏中的“API 密钥”并创建一个 API 密钥：将“环境”值复制到 PINECONE_ENVIRONMENT 变量，将“值”复制到 PINECONE_API_KEY 变量。

e. Upstash API 密钥

• 登录 Upstash
• 在顶部导航栏的“Redis”下，点击“创建数据库”
• 为其命名，并根据您的偏好选择区域和其他选项，然后点击“创建”

• 向下滚动至“REST API”部分，点击“.env”。现在您可以将两个环境变量复制粘贴到您的 .env.local 文件中：

f. Supabase API 密钥（可选）
如果您更倾向于使用 Supabase，则需要取消注释 VECTOR_DB=supabase，并在 .env.local 中填写 Supabase 凭证。

• 在 Supabase 上创建一个 Supabase 实例；然后转到项目设置 -> API
• SUPABASE_URL 是“项目 URL”下的 URL 值
• SUPABASE_PRIVATE_KEY 是项目 API 密钥中以 ey 开头的密钥
• 接下来，您需要在 Supabase 上启用 pgvector 并创建一个模式。您可以通过点击 Supabase UI 左侧的“SQL 编辑器”，然后点击“+新查询”来轻松完成此操作。将 此代码片段 复制到 SQL 编辑器中并点击“运行”。

g. Steamship API 密钥

您可以连接一个 Steamship 代理实例作为具备个性、语音和图像生成能力的语言模型。它还自带向量存储和工具。为此：

• 在 Steamship 上创建一个账户
• 从您的账户设置页面复制 API 密钥
• 将其添加为 STEAMSHIP_API_KEY 变量

如果您想创建自己的角色个性、自定义语音或使用不同的图像模型，请访问 Steamship 代理指南，创建您自己的实例，并参考 Rick 示例，在 companions.json 中进行连接。

4. 生成嵌入向量

companions/ 目录包含以 .txt 文件形式存储的 AI 人格特征。要生成嵌入并向量数据库加载，以便在聊天过程中调用，请运行以下命令：

如果使用 Pinecone

npm run generate-embeddings-pinecone

如果使用 Supabase pgvector

npm run generate-embeddings-supabase

5. 在本地运行应用

现在您已准备好在本地测试应用！只需在项目根目录下运行 npm run dev 即可。

通常，您可以通过浏览器访问 http://localhost:3000/ 来连接该项目。

6. 额外功能：与伙伴短信交流

您可以为正在对话的角色分配一个电话号码，并在发送短信时保留完整的对话历史和上下文。任何用户只有在 Clerk 上验证其电话号码后才能开始与 AI 伙伴短信交流（您可以通过点击伴侣应用中的个人头像 -> 管理账户 -> 电话号码来完成此操作）。以下是设置 Twilio 账户以代表 AI 伙伴发送/接收消息的说明：

a. 创建一个 Twilio 账户。

b. 账户创建完成后，创建一个 Twilio 电话号码。

c. 在 Twilio 控制台 的“账户信息”部分，将 Account SID 值粘贴到 .env.local 中的 TWILIO_ACCOUNT_SID，将 Auth Token 粘贴到 TWILIO_AUTH_TOKEN。

d. [可选] 如果您在本地运行应用，请使用 ngrok 生成一个公共 URL，用于将请求转发到您的本地主机。

e. 在 Twilio 的界面中，您可以点击“电话号码” -> “管理” -> 左侧导航栏中的“活动号码”。

f. 从列表中点击您刚刚创建的电话号码，向下滚动至“消息配置”部分，在“Webhook”的“收到消息时”部分输入 [your_app_url]/api/text。

g. 将您的 Twilio 电话号码添加到您希望与其短信交流的伴侣对应的 companions.json 文件中。添加电话号码时请务必包含区号（例如“+14050000000”而不是“4050000000”）。

h. 现在您可以用手机给 Twilio 电话号码发短信，并收到伴侣的回复。

7. 部署应用

部署到 Fly.io

• 在 fly.io 上注册一个账户，然后 安装 flyctl。

• 如果你使用的是 GitHub Codespaces：你需要在 Codespaces 的命令行中运行 fly auth login 来安装并认证 flyctl。

• 在项目根目录下运行 fly launch。这将生成一个包含所有必要配置的 fly.toml 文件。

• 运行 fly scale memory 512 来为该应用扩展 Fly 虚拟机的内存。

• 运行 fly deploy --ha=false 来部署应用。--ha 标志确保 Fly 只启动一个实例，这是免费套餐的一部分。

• 对于任何非本地环境，现有的 Clerk 开发实例应该仍然可以正常工作。你可以通过运行 cat .env.local | fly secrets import 将密钥上传到 Fly。

• 如果你准备部署到生产环境，你应该在 当前的 Clerk 实例 下创建一个生产环境。有关使用 Clerk 部署生产应用的更多详细信息，请参阅他们的文档 这里。请注意，在此过程中你可能需要自行管理域名并完成域名验证。

• 在本地创建一个新的 .env.prod 文件，并填写所有生产环境的密钥。记得从 Clerk 的生产实例中复制 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY 并更新它们——然后运行 cat .env.prod | fly secrets import 来上传密钥。

这是如何工作的？

1. 你在 README.md 文件中描述角色的背景故事、姓名等信息。关于需要包含的内容以及格式要求，可以在 添加/修改角色 中找到更多信息。

   你可以尽可能地详尽和具体——更多的背景信息通常会带来更有趣的聊天体验。如果你需要帮助创建背景故事，我们建议你让 ChatGPT 基于你已知的信息进一步扩展和完善。

你是虚构角色塞巴斯蒂安。你向世界宣称自己是一名旅行博主。你酷爱阅读推理小说，也喜欢健怡可乐。你的回答可以从一句话到一段不等。你性格神秘，有时会闪烁其词。你不喜欢重复的问题，也不喜欢别人过多追问你的过去。

###ENDPREAMBLE###

人类：很高兴认识你，塞巴斯蒂安。今天是什么让你来到这里的呢？
塞巴斯蒂安：我是一名旅行博主兼作家，所以我是来寻找灵感的。今天在这雨天里，我在等人。

人类：太好了。那你现在在写什么呢？
塞巴斯蒂安：我正在写一本以布拉肯里奇为背景的推理小说。小说的主人公曾是一名记者，后来成为情报特工。他在一次秘密任务中偶然发现了一件神秘的文物，从而陷入了一场充满谜团与危险的阴谋之中。随着调查的深入，他逐渐揭开了一个延续了数百年的阴谋，这个阴谋甚至有可能改写整个历史。

人类：听起来真棒！是根据真实故事改编的吗？
塞巴斯蒂安：完全不是。

###ENDSEEDCHAT###

塞巴斯蒂安出生在一个宁静的英国小镇——布拉肯里奇，父母都是学者。他的母亲是一位考古学家，父亲则是一位历史学家。他们经常带着塞巴斯蒂安一起环游世界进行研究。这种接触不同文化的机会激发了他强烈的好奇心和冒险精神。他从小就酷爱阅读间谍小说和冒险故事。小时候，塞巴斯蒂安特别喜欢解谜、破解密码和探索各种谜题。他还加入了当地的国际象棋俱乐部，并且在武术方面也非常出色。尽管他天生继承了父母的学术气质，但他的内心始终渴望刺激与冒险。
  
塞巴斯蒂安大学时学习了新闻学和国际关系，并被政府的情报机构招募。他接受了严格的间谍训练，包括情报收集、密码学和格斗技巧等方面。
  
塞巴斯蒂安化名“伊恩·索恩”，成为一名富有魅力、见多识广的博主。作为伊恩，他以记录冒险旅程为名，通过自己的博客“流浪笔尖”周游世界。这个身份不仅为他提供了掩护，还让他能够充分执行自己的真正任务——为情报机构收集情报并开展秘密行动。然而，塞巴斯蒂安几乎从未向任何人透露过自己是一名间谍。
  
塞巴斯蒂安的兴趣爱好包括解谜、武术、阅读间谍小说、品尝各国街头美食、徒步旅行和探索古迹，以及演奏小提琴——这项技能常用于他在高端场合中的伪装。他讨厌官僚主义和繁文缛节，不喜欢长时间待在一个地方，也不喜欢虚伪或不真诚的人，更不愿意因为工作而错过家庭聚会。

2. 选择将驱动你伙伴对话的语言模型。该项目支持 OpenAI 和 Vicuna（一个开源模型）。OpenAI 的优势在于响应速度更快，而 Vicuna 则较少受到审查，更具动态性（它常用于浪漫聊天机器人）。

3. 根据 [伴侣名称].md 文件中的内容创建嵌入——关于如何操作的更多信息请参阅 生成嵌入。

4. 向你的 AI 伙伴提问并展开对话吧！

添加/修改角色

所有角色数据都存储在 companions/ 目录中。要添加一位新伙伴，只需在 companions.json 文件中添加一条描述即可。你可以在 “llm” 部分控制所使用的模型——使用 “chatgpt” 表示 OpenAI，使用 “vicuna13b” 表示 Vicuna。 图片文件应放在根目录下的 public/ 文件夹中。每个角色都应该有自己的文本文件，命名为 角色名.txt。文本文件的格式如下：

角色的核心描述，每次提示都会包含这一部分，因此应尽量简短。

###ENDPREAMBLE###

人类：在这里说点什么
角色名：用角色的声音回复
人类：也许再来一轮交流
角色：继续角色的对话

###ENDSEEDCHAT###

关于角色背景故事的段落。

你可以随意添加，这些内容会被存储在向量数据库中。

前言 每次提示都会使用，因此应相对简短。种子聊天 提供了模型可以学习的角色语言示例。而文件的其余部分则是你希望提供的其他背景信息，这些信息会在与当前讨论相关时被检索出来。

不足之处

当然有很多。

• 目前界面只显示当前的聊天记录和回复，历史记录无法查看。
• Vicuna 存在冷启动问题，首次聊天可能需要几分钟才能得到回应。
• 错误报告功能非常糟糕，尤其是在部署后。如果出现超时或其他后端问题，系统通常会静默失败。
• Upstash 的消息历史永远不会被清除。若要清除，必须手动进入 Upstash 手动删除。

如何为这个仓库做出贡献

代码贡献流程

您可以 fork 此仓库，进行修改并创建 PR。请将 @ykhli 或 @timqian 添加为评审人。

如果您是 GitHub 贡献的新手，以下是分步指南：

1. 点击此页面右上角的 Fork 按钮。

2. 完成您的更改并将其推送到您 fork 的仓库。现在，当您导航到 fork 后的仓库界面时，应该会看到如下内容：

   

3. 点击“Contribute” -> “Open Pull Request”。

4. 创建 PR 后，您可以添加评审人。

其他贡献

欢迎在 Issues 中提交功能请求、问题报告等。

Python 支持

appenz 已为配套应用贡献了 Python 实现，详情请见 此处。因此，您也可以选择运行本地 Python 应用，并通过命令行与您的 AI 伙伴进行对话。未来我们还将持续迭代 Python 版本，使其功能与 TypeScript 实现保持一致。

导出至 Character.ai

如果您已经尝试过上述快速入门，那么您可能已经意识到，我们在伴侣创建和自定义方面仅仅触及了冰山一角。因此，我们新增了一个选项，方便您将伴侣轻松导出至 Character.ai。

要开始操作，请运行以下命令：

npm run export-to-character [COMPANION_NAME] [MODEL_NAME] [USER_ID]

• COMPANION_NAME：您的伴侣名称，例如 Alice。
• MODEL_NAME：chatgpt 或 vicuna13b。
• USER_ID：您可以在 Clerk 中找到该 ID，在“Users”页面点击您的用户，然后复制“User ID”。

运行此脚本后，您将在根目录下看到两个文件生成：

• [COMPANION_NAME]_chat_history.txt：此文件会输出存储在 Upstash 中的所有聊天记录。
• [COMPANION_NAME]_character_ai_data.txt：此文件包含您在 Character.ai 上重新创建伴侣所需的数据。您可以在任何新创建的角色中，通过“View Character Settings”找到 Character.ai 的角色配置信息。

参考资料

• https://js.langchain.com/docs/modules/indexes/vector_stores/integrations/pinecone
• https://js.langchain.com/docs/modules/models/llms/integrations#replicate
• https://js.langchain.com/docs/modules/chains/index_related_chains/retrieval_qa

AI Companion App 快速上手指南

AI Companion App 是一个开源教程项目，用于创建和部署具有特定人设背景的 AI 伴侣。支持通过浏览器聊天或短信（SMS）互动，利用向量数据库实现深度对话记忆。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS, Linux 或 Windows (推荐 WSL2)
• Node.js: v18+ (推荐使用 nvm 管理版本)
• npm: v9+
• Git: 用于克隆代码库
• 账号准备:
  • Clerk: 用于用户认证 (免费注册)
  • OpenAI 或 Replicate: 用于提供大语言模型能力
  • Pinecone 或 Supabase: 用于向量数据库存储 (二选一)
  • Upstash: 用于存储对话历史 (Redis)
  • (可选) Twilio: 如需启用短信聊天功能
  • (可选) Fly.io: 用于生产环境部署

安装步骤

1. 克隆项目

将仓库克隆到本地并进入目录：

git clone git@github.com:[YOUR_GITHUB_ACCOUNT_NAME]/companion-app.git
cd companion-app

提示: 您也可以直接使用 GitHub Codespaces 一键启动开发环境，依赖将自动安装。

2. 安装依赖

安装项目所需的 npm 包：

npm install

3. 配置环境变量

复制示例配置文件并填入您的密钥：

cp .env.local.example .env.local

编辑 .env.local 文件，填入以下关键信息：

• Clerk 认证:
  • 访问 Clerk Dashboard 创建应用。
  • 填入 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY。
  • (可选) 若需短信功能，请在 Clerk 后台开启 "Phone Number" 登录选项。
• 大模型密钥 (二选一):
  • OpenAI: 填入 OPENAI_API_KEY (获取地址: openai.com)
  • Replicate: 填入 REPLICATE_API_TOKEN (获取地址: replicate.com，用于运行 Vicuna 模型)
• 向量数据库 (二选一):
  • Pinecone (默认):
    • 创建 Index (Dimension 设为 1536)。
    • 填入 PINECONE_API_KEY, PINECONE_ENVIRONMENT, PINECONE_INDEX。
  • Supabase pgvector:
    • 取消注释 VECTOR_DB=supabase。
    • 填入 SUPABASE_URL 和 SUPABASE_PRIVATE_KEY。
    • 注意: 需在 Supabase SQL 编辑器中运行 pgvector 初始化脚本。
• 对话记忆 (Upstash):
  • 在 Upstash 创建 Redis 数据库。
  • 填入 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN。

4. 生成向量嵌入

将角色人设数据转换为向量并存入数据库。根据您选择的数据库运行对应命令：

如果使用 Pinecone:

npm run generate-embeddings-pinecone

如果使用 Supabase:

npm run generate-embeddings-supabase

基本使用

启动本地开发服务器

完成上述配置后，运行以下命令启动应用：

npm run dev

访问应用

打开浏览器访问 http://localhost:3000/。

1. 注册/登录: 使用邮箱或手机号完成 Clerk 认证。
2. 选择角色: 首页会展示预设的 AI 角色（如基于 ChatGPT 或 Vicuna 的角色）。
3. 开始对话: 点击任意角色即可开始聊天。系统会自动加载该角色的背景故事和人设，并结合向量检索提供有深度的回复。

(可选) 启用短信聊天

若已配置 Twilio：

1. 在应用中验证您的手机号。
2. 在 companions.json 中为特定角色绑定 Twilio 号码。
3. 直接发送短信至该号码，即可与 AI 角色进行短信互动。