PeterCat-在任意网站内接入AI知识库智能答疑机器人

介绍

PeterCat是专为社区维护者和开发者打造的智能答疑机器人解决方案。

官网：https://petercat.ai

Github：https://github.com/petercat-ai/petercat

banner

特性

它提供对话式答疑 Agent 配置系统、自托管部署方案和便捷的一体化应用 SDK，让您能够为自己的 GitHub 仓库一键创建智能答疑机器人，并快速集成到各类官网或项目中， 为社区提供更高效的技术支持生态。

对话即创造

仅需要告知你的仓库地址或名称，PeterCat 即可自动完成创建机器人的全部流程

对话即创造

知识自动入库

机器人创建后，所有相关Github 文档和 issue 将自动入库，作为机器人的知识依据

知识自动入库

多平台集成

多种集成方式自由选择，如对话应用 SDK 集成至官网，Github APP一键安装至 Github 仓库等

官网

使用效果

如何接入

使用官方实例接入

  • 首先登录官网后选择工作台，创建自己的空间
  • 创建项目进入配置，可以手动和对话配置
  • 复制 Token后选择保存部署，填写域名提交给官方审核

1734939987253

审核通过（将你的域名加入白名单）后，可以选择不同的代码接入

参考文档：https://github.com/petercat-ai/petercat/blob/main/assistant/src/Assistant/index.md#api

代码引入

1
npm install @petercatai/assistant
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { Assistant } from '@petercatai/assistant';
import '@petercatai/assistant/style';

const YourPetercataiAssistant = () => {
  return <Assistant token="< 你的 token >" showBubble={true} isVisible={false} apiDomain="https://api.petercat.ai" />;
};

function App() {
  const [count, setCount] = useState(0);

  return (
    <>
      {/* ... */}
      <YourPetercataiAssistant />
    </>
  );
}

其他

UMD 接入

petercat 同时支持 UMD 的接入方式

  1. external 和 UMD 加载资源
1
2
3
4
5
6
7
8
9
10
11
// example for umi project
// .umirc.ts
export default {
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM',
    antd: 'antd',
    dayjs: 'dayjs',
    'lottie-web': 'lottie',
  },
};

PHP+HTML页面引入

1
2
3
4
5
6
7
8
9
<head>
  <script src="https://cdn.jsdelivr.net/npm/react/umd/react.development.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/react-dom/umd/react-dom.development.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/dayjs/dayjs.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/antd/dist/antd.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/lottie-web/build/player/lottie.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/@petercatai/assistant@1.0.7/dist/umd/assistant.min.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@petercatai/assistant@1.0.7/dist/umd/assistant.min.css">
</head>

加载 PetercatLUI

1
2
3
4
5
6
7
8
9
10
11
<body>
  ...
   <script>
     PetercatLUI.initAssistant({
       apiDomain: 'https://api.petercat.ai',
       token: 'your-token',
       starters: ['介绍下这个项目', '查看贡献指南', '我该怎样快速上手'],
       clearMessage: true
     });
  </script>
</body>

私有化部署

部署方案支持：AWS + Supabase

自托管

本地安装

第一步：克隆仓库

将项目仓库克隆到本地计算机：

1
git clone https://github.com/petercat-ai/petercat.git

第二步：安装依赖

使用 Yarn 安装所有必需的依赖项：

1
yarn run bootstrap

第三步：在本地启动 supabase

参考 https://supabase.com/docs/guides/self-hosting/docker#installing-and-running-supabase

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Get the code
git clone --depth 1 https://github.com/supabase/supabase

# Go to the docker folder
cd supabase/docker

# Copy the fake env vars
cp .env.example .env

# Pull the latest images
docker compose pull

# Start the services (in detached mode)
docker compose up -d

第四步：复制 .env.example 文件

复制客户端环境配置示例文件：

1
cp client/.env.local.example client/.env

复制服务器环境配置示例文件：

1
cp server/.env.local.example server/.env

打开 server/.env 文件，把 SERVICE_ROLE_KEY 字段改成从 supabase 的 docker/.env 文件的 SERVICE_ROLE_KEY 的值

第五步：初始化数据库结构

第五步 5.1：导航到 Migrations 文件夹

导航到 migrations 文件夹，准备进行数据库设置：

1
cd migrations

第五步 5.2：安装 Supabase CLI

按照 Supabase 入门指南 中的说明安装 Supabase CLI：

1
brew install supabase/tap/supabase

第五步 5.3：执行迁移

将数据库迁移应用到您的远程数据库：

1
2
# postgres db url 在第四步的 .env 文件中可以找到
supabase db push --db-url "postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@127.0.0.1:5432/postgres"

如果成功，您将看到类似以下的输出：

1
2
3
4
5
6
7
Connecting to remote database...
Do you want to push these migrations to the remote database?
• 20240902023033_remote_schema.sql

[Y/n] Y
Applying migration 20240902023033_remote_schema.sql...
Finished supabase db push.

第六步：启动服务器

使用以下命令启动服务器：

1
yarn run server:local

通过在浏览器中打开 http://127.0.0.1:8001/api/health_checker 检查服务器是否正在运行。

第七步：启动客户端

使用以下命令启动客户端：

1
yarn run client

您可以通过在浏览器中打开 http://127.0.0.1:3000 来检查客户端服务。

在 AWS 上部署 Petercat：准备步骤

在 AWS 上部署 Petercat 之前，请确保您已完成以下准备工作：

  • 开通 AWS 账户。
  • 本地安装 Docker。

示例：在亚太区 - 新加坡（ap-southeast-1）本地部署您的服务

第一步：安装 AWS CLI 和 SAM CLI

  1. 安装 AWS CLI 工具。
  2. 访问配置文档并配置您的 AWS CLI：AWS CLI 配置指南
  3. 安装 SAM CLI 工具。
  4. 访问 SAM CLI 安装指南。

第二步：登录 AWS

使用单点登录 (SSO) 会话登录您的 AWS 账户：

1
aws sso login --sso-session $YOUR_PROFILE_NAME

第三步：复制并修改配置文件

运行以下命令复制示例配置文件：

1
cp .aws/petercat-example.toml .aws/petercat-ap-southeast.toml

第四步：更新 .toml 文件

打开 .toml 文件并更新必要的键值。您可以使用任何文本编辑器，例如 vim、emacs、vscode 或 nano：

1
vim .aws/petercat-ap-southeast.toml

将 YOUR_REGION 替换为 ap-southeast-1，并将 YOUR_STACK_NAME 替换为您的自定义栈名称，例如 petercat-selfhosted。

1
2
3
4
5
6
7
8
9
version = 0.1
[default.deploy.parameters]
stack_name = "petercat-selfhosted"
resolve_s3 = true
s3_prefix = "petercat-selfhosted"
region = "ap-southeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true

第五步：本地构建 Docker 镜像

在项目的根目录中运行以下命令。根据您计算机的配置，这一步可能需要一些时间：

1
sam build --use-container --config-file .aws/petercat-ap-southeast.toml

构建完成后，您应该会看到以下输出：

1
2
3
4
5
6
7
8
9
10
11
Build Succeeded

Built Artifacts  : .aws-sam/build
Built Template   : .aws-sam/build/template.yaml

Commands you can use next
=========================
[*] Validate SAM template: sam validate
[*] Invoke Function: sam local invoke
[*] Test Function in the Cloud: sam sync --stack-name {{stack-name}} --watch
[*] Deploy: sam deploy --guided

第六步：加载环境变量并开始部署

在根目录中，执行以下命令以加载环境变量：

1
source server/.env

然后，运行以下命令进行部署：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
sam deploy \
    --guided \
    --no-confirm-changeset \
    --config-file .aws/petercat-ap-southeast.toml \
    --parameter-overrides APIUrl=$API_URL \
                          WebUrl=$WEB_URL \
                          AWSSecretName=$X_GITHUB_SECRET_NAME \
                          S3TempBucketName=$S3_TEMP_BUCKET_NAME \
                          GitHubAppID=$X_GITHUB_APP_ID \
                          GithubAppsClientId=$X_GITHUB_APPS_CLIENT_ID \
                          GithubAppsClientSecret=$X_GITHUB_APPS_CLIENT_SECRET \
                          OpenAIAPIKey=$OPENAI_API_KEY \
                          GeminiAPIKey=$GEMINI_API_KEY \
                          SupabaseServiceKey=$SUPABASE_SERVICE_KEY \
                          SupabaseUrl=$SUPABASE_URL \
                          TavilyAPIKey=$TAVILY_API_KEY \
                          APIIdentifier=$API_IDENTIFIER \
                          FastAPISecretKey=$FASTAPI_SECRET_KEY \
                          Auth0Domain=$AUTH0_DOMAIN \
                          Auth0ClientId=$AUTH0_CLIENT_ID \
                          Auth0ClientSecret=$AUTH0_CLIENT_SECRET

第七步：检查您的服务

查看 CloudFormation 部署栈的输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
------------------------------------------------------------------------------------------------------------------------------------
Outputs
------------------------------------------------------------------------------------------------------------------------------------
Key                 FastAPIFunction
Description         FastAPI Lambda Function ARN
Value               arn:aws:lambda:ap-southeast-1:654654285942:function:petercat-selfhosted-FastAPIFunction-x0bez5v1EMDL

Key                 SQSSubscriptionFunction
Description         SQS Subscription Function Lambda Function ARN
Value               arn:aws:lambda:ap-southeast-1:654654285942:function:petercat-selfhosted-SQSSubscriptionFunction-ghluUSulMO4y

Key                 FastAPIFunctionUrl
Description         Function URL for FastAPI function
Value               https://itebdgout4h33aqpy2ygxaedgm0nlnys.lambda-url.ap-southeast-1.on.aws/

Key                 SQSSubscriptionFunctionUrl
Description         Function URL for SQS Subscription function
Value               https://q7kpxukbpgxkkjldgnvvbc6dyi0akzuk.lambda-url.ap-southeast-1.on.aws/
------------------------------------------------------------------------------------------------------------------------------------

使用 curl 测试您的服务：

1
curl https://itebdgout4h33aqpy2ygxaedgm0nlnys.lambda-url.ap-southeast-1.on.aws/api/health_checker

环境变量

本项目需要进行环境变量进行设置：

Client

1
.env.local
环境变量 类型 描述 示例
NEXT_PUBLIC_API_DOMAIN 必选 后端服务的 API 域名。 https://api.petercat.ai

Server

1
.env
环境变量 类型 描述 示例
应用基础环境变量
API_URL 必选 后端服务的 API 域名 https://api.petercat.ai
WEB_URL 必选 前端 Web 服务的域名 https://petercat.ai
STATIC_URL 必选 静态资源域名 https://static.petercat.ai
AWS 相关环境变量
X_GITHUB_SECRET_NAME 必选 AWS 托管的 Github 私钥文件名 prod/githubapp/petercat/pem
STATIC_SECRET_NAME 可选 AWS 托管的 CloudFront 签名私钥名称。如果配置了该项，将使用 CloudFront 签名 URL 来保护你的资源。更多信息请参阅 AWS 文档。 prod/petercat/static
LLM_TOKEN_SECRET_NAME 可选 AWS 托管的 llm 签名私钥名称。如果配置了该项，petercat 将使用 RSA 算法托管用户的 LLM Token prod/petercat/llm
LLM_TOKEN_PUBLIC_NAME 可选 AWS 托管的 llm 签名公钥名称。如果配置了该项，petercat 将使用 RSA 算法托管用户的 LLM Token prod/petercat/llm/pub
STATIC_KEYPAIR_ID 可选 AWS CloudFront 的 Key Pair ID。如果配置了该项，将使用 CloudFront 签名 URL 来保护你的资源。更多信息请参阅 AWS 文档。 APKxxxxxxxx
S3_TEMP_BUCKET_NAME 可选 用于托管 AWS 临时图片文件 S3 的 bucket xxx-temp
SQS_QUEUE_URL 必选 AWS SQS 消息队列 URL https://sqs.ap-northeast-1.amazonaws.com/xxx/petercat-task-queue
SUPABASE 相关 env
SUPABASE_URL 必选 supabase 服务的 URL，可以在这里找到 https://***.supabase.co
SUPABASE_SERVICE_KEY 必选 supabase 服务密钥，可以在这里找到 {{SUPABASE_SERVICE_KEY}}
Auth0 相关 env
AUTH0_DOMAIN 必选 auth0 服务域名，从 auth0 / Application / Basic Information 下获取 petercat.us.auth0.com
AUTH0_CLIENT_ID 必选 auth0 客户端 ID，从 auth0 / Application / Basic Information 下获取 artfiUxxxx
AUTH0_CLIENT_SECRET 必选 auth0 客户端密钥， 从 auth0 / Application / Basic Information 下获取 xxxx-xxxx-xxx
API_IDENTIFIER 必选 auth0 的 API Identifier https://petercat.us.auth0.com/api/v2/
LLM相关的 env
OPENAI_API_KEY 必选 OpenAI 的密钥 sk-xxxx
OPENAI_BASE_URL 可选 API 请求的基础 URL。仅在使用代理或服务模拟器时指定。 https://api.openai.com/v1
GEMINI_API_KEY 可选 Gemini 的密钥 xxxx
TAVILY_API_KEY 必选 Tavily 的密钥 tvly-xxxxx
注册为 Github App 的 env
X_GITHUB_APP_ID 可选 注册为 Github App 时，APPID 123456
X_GITHUB_APPS_CLIENT_ID 可选 注册为 Github App 时，APP 的 Client ID Iv1.xxxxxxx
X_GITHUB_APPS_CLIENT_SECRET 可选 注册为 Github App 时，APP 的 Client 密钥 xxxxxxxx
限流配置
RATE_LIMIT_ENABLED 可选 限流配置是否开启 True
RATE_LIMIT_REQUESTS 可选 限流的请求数量 100
RATE_LIMIT_DURATION 可选 限流的统计时长，单位为分钟 1