################################################################################
# ____ _ ____ _ _ #
# / ___|___ | |__ ___ _ __ ___ / ___| __ _ _ __ __| | |__ _____ __ #
# | | / _ \| '_ \ / _ \ '__/ _ \ \___ \ / _` | '_ \ / _` | '_ \ / _ \ \/ / #
# | |__| (_) | | | | __/ | | __/ ___) | (_| | | | | (_| | |_) | (_) > < #
# \____\___/|_| |_|\___|_| \___| |____/ \__,_|_| |_|\__,_|_.__/ \___/_/\_\ #
# #
# 本项目是 Cohere Sandbox 一部分,这是 Cohere 的实验性开源产品。该项目提供了一个使用 Cohere 平台的库、工具或演示。您应该期待(自我)记录的高质量代码,但请注意这是实验性的。因此,随着库、工具或演示的演进,也请期待可能的问题、不向后兼容的更改或功能变化。如果在您的任务关键性代码中依赖此项目,请考虑引用特定的 git 提交或版本。 #
# #
# 请随时提出问题或提交拉取请求,感谢您关注此项目! #
# #
################################################################################
**维护者:** [Cohere ConvAI 团队](mailto:convai@cohere.com) \
**项目至少维护到(YYYY-MM-DD):** 2023-03-01
# Conversant
[![tests](https://yellow-cdn.veclightyear.com/2b54e442/e946f45d-3e96-4aef-91a7-20f77400aed8.svg)](https://yellow-cdn.veclightyear.com/2b54e442/e946f45d-3e96-4aef-91a7-20f77400aed8.svg)
[![PyPI](https://yellow-cdn.veclightyear.com/2b54e442/7626237d-ce92-4424-b2b2-825b08554a43.svg)](https://yellow-cdn.veclightyear.com/2b54e442/7626237d-ce92-4424-b2b2-825b08554a43.svg)
[![License: MIT](https://yellow-cdn.veclightyear.com/2b54e442/4d3a30f9-54ec-45bc-9d8c-ba0a1c93afb5.svg)](https://opensource.org/licenses/MIT)
在 [Cohere](https://cohere.ai/) 的[大语言模型](https://docs.cohere.ai/generate-reference/)之上构建会话 AI
- 🗣 使用 Cohere 的 [API](https://docs.cohere.ai/api-reference/) 快速使用大型语言模型
- 😃 自定义角色
- 💁 将聊天记录的管理交给 `conversant`
- 🪨 在您提供的事实基础上进行对话(即将推出!)
- 🐍 使用 pip 安装 `conversant`
`conversant` 是一个构建可定制对话代理(也称为聊天机器人)的正在进行中的框架,可以使用各种不同的聊天机器人角色回答问题与用户进行对话。`conversant` 旨在提供模块化、灵活性和可扩展性,以便您创建任何想要的聊天机器人!
我们为您提供了几种自定义角色,包括 🧑💼 客户支持代理,⌚️ 手表销售代理,🧑🏫 数学老师,和 🧙 幻想巫师。只需用描述和一些示例对话即可创建您自己的角色!
阅读更多关于 `conversant` 如何成为 Cohere Sandbox 一部分的信息,请查看我们的[启动博客文章](https://txt.cohere.ai/introducing-sandbox-coheres-experimental-open-source-initiative/)。
在我们的 Streamlit 演示上试用 `conversant` [这里](https://conversant.streamlit.app/)! 🎉
## 目录
1. [安装和使用](#installation-and-usage)
1. [安装](#installation)
2. [Streamlit 演示](#streamlit-demo)
3. [运行您自己的 Streamlit 演示](#running-your-own-streamlit-demo)
4. [创建自定义角色](#creating-a-custom-persona)
5. [在演示中编辑角色](#editing-a-persona-on-the-demo)
6. [使用](#usage)
2. [Conversant 的工作原理](#how-conversant-works)
3. [文档](#documentation)
4. [获得支持](#get-support)
5. [贡献指南](#contributing-guidelines)
6. [许可证](#license)
## 安装和使用
### 安装
`conversant` 可以在 [PyPI](https://pypi.org/project/conversant/) 上获取,并在 Python 3.8+ 版本和 [Cohere](https://pypi.org/project/cohere/) 2.8.0+ 版本上进行了测试。
pip install conversant
### Streamlit 演示
想先看看它的实际应用吗?您可以在 [Streamlit](https://docs.streamlit.io/) 应用上使用 `conversant`,无需安装任何东西 [这里](https://conversant.streamlit.app/)! 🎉
<p float="none">
<img src="https://yellow-cdn.veclightyear.com/2b54e442/3424ce15-34ba-4289-bcc2-d7ba76797b32.png" alt="显示 Streamlit 演示中可用角色的截图,默认选择了算命师角色。" height="550"/>
<img src="https://yellow-cdn.veclightyear.com/2b54e442/da35fe21-2a68-4eb4-8086-77f4a5af722c.png" alt="显示算命师聊天机器人和用户之间对话的截图。" height="550"/>
</p>
### 运行您自己的 Streamlit 演示
Cohere 使用 Streamlit 创建其演示应用程序。如果您是 Streamlit 新手,您可以[在这里](https://docs.streamlit.io/library/get-started/installation) 安装并阅读更多关于运行 Streamlit 命令的内容[这里](https://docs.streamlit.io/library/get-started/main-concepts)。
如果您希望在本地修改此 Streamlit 演示,我们强烈建议派生此仓库,而不是从 PyPI 安装它作为库。
如果您希望启动自己的 Streamlit 演示实例,您首先需要一个 `COHERE_API_KEY`。
您可以通过访问 [dashboard.cohere.ai](https://dashboard.cohere.ai/welcome/register?utm_source=github&utm_medium=content&utm_campaign=sandbox&utm_content=conversant) 生成一个。
#### 本地 Streamlit 应用程序
如果您计划在本地运行 Streamlit 应用程序,您可以将密钥添加到 `.streamlit/secrets.toml`:
COHERE_API_KEY = "YOUR_API_KEY_HERE"
在本地运行时,Streamlit 将读取 `secrets.toml` 文件并默默地将这些值注入到环境变量中。或者,您也可以通过从命令行运行以下命令直接将 API 密钥设置为环境变量:
export COHERE_API_KEY = "YOUR_API_KEY_HERE"
从命令行启动 Streamlit 应用程序,使用以下命令:
streamlit run conversant/demo/streamlit_example.py
#### 托管 Streamlit 应用程序
如果您希望创建一个托管 Streamlit 应用程序,可以通过[秘密管理](https://docs.streamlit.io/streamlit-cloud/get-started/deploy-an-app/connect-to-data-sources/secrets-management)将您的 Cohere API 密钥添加到 Streamlit。将以下内容作为一个 Secret 添加:
COHERE_API_KEY = "YOUR_API_KEY_HERE"
创建自定义角色
一旦你有了自己的 Streamlit 应用实例,就可以开始尝试创建自定义角色了!查看 conversant/personas
目录中的每个角色的 config.json
。你需要在此目录中创建一个对应于新角色的子文件夹,并添加一个 config.json
文件。
请注意,我们强烈建议分叉 sandbox-conversant-lib
仓库,而不是从 PyPI 安装它作为库。当你创建一个新角色时,请使用克隆仓库中的 personas
目录。目录结构应如下所示:
conversant/personas
├── fortune-teller
│ └── config.json
└── your-persona-name # new
└── config.json
配置文件应包含以下内容:
chatbot_config
:max_context_examples
: 聊天机器人用来回复的聊天历史长度。avatar
: 聊天机器人的头像(可选的 emoji 简码或图像 URL)。默认为 🤖。
client_config
:co.generate()
的参数chat_prompt_config
:preamble
: 对角色的描述。example_separator
: 分隔每个示例对话的字符串。headers
:bot
和user
的名称。examples
: 一些对话示例(少样本),或为空(零样本)。
conversant
会处理其余的内容!例如,查看 fortune-teller/config.json
。当你启动 Streamlit 应用时,新角色将出现在下拉菜单中。
使用自定义角色子集运行应用
如果你希望使用自定义角色子集运行应用,可以创建一个只包含所需角色的新目录。这类似于 conversant/personas
目录,结构需要保持一致:
custom-personas
├── your-first-persona
│ └── config.json
└── your-second-persona
└── config.json
创建此目录后,你需要告知应用从哪里查找。在示例 Streamlit 应用 (streamlit_example.py
) 中,第一行之一为 CUSTOM_PERSONA_DIRECTORY = None
。将其更改为指定所需的角色目录,例如 CUSTOM_PERSONA_DIRECTORY = "/Users/yourname/custom-personas"
。
如果此项未更改,应用将默认使用包含 conversant
示例角色的目录。
解决缺少角色的问题
如果在下拉菜单中未看到新角色,则可能需要指定自定义角色目录。按照上面的说明告知应用从哪里查找角色。
在演示中编辑角色
你也可以在 Streamlit 应用上编辑角色!
使用
通过 conversant
,你可以使用 Cohere 的大型语言模型创建一个聊天机器人,只需以下代码片段。
import cohere
import conversant
co = cohere.Client("YOUR_API_KEY_HERE")
bot = conversant.PromptChatbot.from_persona("fantasy-wizard", client=co)
print(bot.reply("Hello!"))
>>> "Well met, fair traveller. What bringest thou to mine village?"
你也可以通过传入自己的 ChatPrompt
定义自己的角色。
from conversant.prompts import ChatPrompt
shakespeare_config = {
"preamble": "Below is a conversation between Shakespeare and a Literature Student.",
"example_separator": "<CONVERSATION>\n",
"headers": {
"user": "Literature Student",
"bot": "William Shakespeare",
},
"examples": [
[
{
"user": "Who are you?",
"bot": "Mine own nameth is Shakespeare, and I speaketh in riddles.",
},
]
],
}
shakespeare_bot = conversant.PromptChatbot(
client=co, prompt=ChatPrompt.from_dict(shakespeare_config)
)
print(shakespeare_bot.reply("Hello!"))
>>> "Greeteth, and welcome. I am Shakespeare, the great poet, dramatist, and playwright."
Conversant 的工作原理
conversant
使用提示完成来定义聊天机器人角色,使用描述和一些示例。提示作为输入发送到 Cohere 的 co.generate()
端点,给自回归语言模型生成文本,通过示例和当前对话上下文以少样本方式生成文本。
每个用户消息和聊天机器人回复都会附加到聊天历史记录中,以便未来的回复基于当时的对话上下文。
在未来,我们计划增加功能,使聊天机器人能够使用从本地文档缓存中检索的文本进行事实性确认。
更多信息,请参见CONTRIBUTORS.md
中的本节。
文档
完整的文档可以在这里找到。
获取支持
如果你有任何问题或意见,请提交问题或在Discord上联系我们。
贡献指南
如果你想为该项目做贡献,请阅读此仓库中的 CONTRIBUTORS.md
,并在提交任何拉取请求之前签署贡献者许可证协议。第一次向 Cohere 仓库提出拉取请求时,将生成一个签署 Cohere CLA 的链接。
除了提交代码到此仓库的指南外,CONTRIBUTORS.md
包含了帮助开发者入门的演练以及解释 conversant
底层工作原理的示意图。:wrench:
许可证
conversant
具有 MIT 许可证。