PerBridge

Perplexity API 兼容的适配器服务

将开源 Perplexica 转换为 Perplexity API 兼容接口

📖 项目概述

PerBridge 是一个轻量级的适配器服务，旨在为开源搜索 AI 项目 Perplexica 提供完全兼容 Perplexity AI API 的接口。通过 PerBridge，您可以：

无缝集成：让现有使用 @ai-sdk/perplexity 的应用直接连接到自托管的 Perplexica 实例
格式转换：自动处理 Perplexity API 和 Perplexica API 之间的请求/响应格式转换
流式支持：完整支持流式和非流式响应模式
灵活配置：支持丰富的环境变量配置，适应不同的部署需求

🏗️ 架构原理

客户端应用 (@ai-sdk/perplexity)
    ↓ Perplexity API 格式请求
PerBridge 适配器服务
    ↓ 转换为 Perplexica API 格式
Perplexica 开源搜索服务
    ↓ 返回搜索结果
PerBridge 适配器服务
    ↓ 转换为 Perplexity API 格式响应
客户端应用接收标准响应

🚀 快速开始

前置要求

Node.js 18+
npm 或 yarn
运行中的 Perplexica 实例

安装步骤

克隆仓库

git clone https://github.com/zhang157686/perbridge

cd perbridge

安装依赖

npm install

配置环境变量

# 复制环境变量示例文件
cp env.example .env

# 编辑 .env 文件，配置相关的环境变量
nano .env  # 或使用您喜欢的编辑器

启动服务

# 开发模式（自动重启）
npm run dev

# 或生产模式
npm start

验证服务

# 检查服务健康状态
curl http://localhost:3601/health

# 测试基本功能（需要提供 API 密钥）
curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"model":"nono"}'

⚙️ 配置详解

PerBridge 通过环境变量进行配置。以下是所有可用的配置选项：

🖥️ 服务器配置

环境变量	默认值	说明
`PORT`	`3601`	PerBridge 服务监听端口
`HOST`	`localhost`	服务绑定的主机地址
`NODE_ENV`	`development`	运行环境 (`development` / `production`)

🔗 Perplexica 连接配置

环境变量	默认值	说明
`PERPLEXICA_API_URL`	`http://localhost:3000`	Perplexica 服务器的 API 地址
`FOCUS_MODE`	`webSearch`	搜索焦点模式 (`webSearch`, `academicSearch`, `writingAssistant`, `wolframAlpha`, `youtubeSearch`, `redditSearch`)
`OPTIMIZATION_MODE`	`speed`	优化模式 (`speed` / `balanced`)
`SYSTEM_INSTRUCTIONS`	`You are a helpful AI assistant...`	系统指令，用于指导 AI 的回答风格

🤖 模型配置

PerBridge 支持通过 JSON 格式配置 Perplexica 使用的模型：

聊天模型配置

# 使用 Ollama 本地模型
CHAT_MODEL_JSON='{"provider": "ollama", "name": "llama3"}'

# 使用 OpenAI 模型
CHAT_MODEL_JSON='{"provider": "openai", "name": "gpt-4"}'

# 使用 Anthropic 模型
CHAT_MODEL_JSON='{"provider": "anthropic", "name": "claude-3-sonnet"}'

嵌入模型配置

# 使用 OpenAI 嵌入模型
EMBEDDING_MODEL_JSON='{"provider": "openai", "name": "text-embedding-3-large"}'

# 使用 Ollama 嵌入模型
EMBEDDING_MODEL_JSON='{"provider": "ollama", "name": "nomic-embed-text"}'

说明：CHAT_MODEL_JSON 和 EMBEDDING_MODEL_JSON 为可选参数，如果不设置，默认使用您 Perplexica 服务中配置的模型。

🎭 Perplexity API 兼容性配置

环境变量	默认值	说明
`PLACEHOLDER_MODEL_NAME`	`nono`	在 Perplexity API 响应中显示的模型名称

🔒 安全配置

环境变量	默认值	说明
`PERPLEXITY_API_KEY`	必填	API 密钥验证，用于验证客户端请求的身份
`CORS_ORIGIN`	`*`	CORS 允许的源地址
`RATE_LIMIT_WINDOW_MS`	`900000`	速率限制时间窗口（毫秒）
`RATE_LIMIT_MAX_REQUESTS`	`100`	时间窗口内最大请求数

🔐 API 密钥验证

PerBridge 现在需要有效的 API 密钥来访问所有端点。这提供了基本的安全保护，防止未授权访问。PERPLEXITY_API_KEY 并非实际的 Perplexity 官网申请的 API 密钥，而是自己设置的，别的客户端请求本服务（PerBridge）时需要设置 PERPLEXITY_API_KEY 为你自己设置的密钥值，一来是为了兼容 Perplexity 的请求格式，二来是为了为本服务进行安全认证。

配置 API 密钥：

# 在 .env 文件中设置您的密钥
PERPLEXITY_API_KEY=your_secret_api_key_here

客户端使用 API 密钥的方式：

Authorization Header（推荐）

curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

Bearer Token 格式

curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: Bearer your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

请求体中的 api_key 字段

curl -X POST http://localhost:3601/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_secret_api_key_here",
    "messages":[{"role":"user","content":"Hello"}]
  }'

查询参数

curl -X POST "http://localhost:3601/chat/completions?api_key=your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

📝 日志配置

环境变量	默认值	说明
`LOG_LEVEL`	`info`	日志级别 (`error`, `warn`, `info`, `debug`)

📋 完整配置示例

# 服务器配置
PORT=3601
HOST=0.0.0.0
NODE_ENV=production

# API 密钥验证（必填）
PERPLEXITY_API_KEY=your_secure_api_key_here_change_this

# Perplexica 连接
PERPLEXICA_API_URL=https://your-perplexica-instance.com
FOCUS_MODE=webSearch
OPTIMIZATION_MODE=speed
SYSTEM_INSTRUCTIONS=You are a helpful research assistant that provides accurate, well-sourced information.

# 模型配置
CHAT_MODEL_JSON={"provider": "openai", "name": "gpt-4"}
EMBEDDING_MODEL_JSON={"provider": "openai", "name": "text-embedding-3-large"}

# API 兼容性
PLACEHOLDER_MODEL_NAME=nono

# 安全配置
CORS_ORIGIN=*
RATE_LIMIT_WINDOW_MS=3600000
RATE_LIMIT_MAX_REQUESTS=1000

# 日志
LOG_LEVEL=warn

🎯 使用方法

在现有应用中使用

如果您已经有使用 @ai-sdk/perplexity 的应用，需要修改 API 基础 URL 和 API 密钥：

import { createPerplexity } from "@ai-sdk/perplexity";

const perplexity = createPerplexity({
  apiKey: "your_secret_api_key_here", // 使用您在 .env 中配置的 PERPLEXITY_API_KEY
  baseURL: "http://localhost:3601", // 指向您的 PerBridge 实例
});

// 其余代码保持不变
const { text } = await generateText({
  model: perplexity("nono"),
  messages: [{ role: "user", content: "What is the latest news about AI?" }],
});

直接 HTTP 请求

⚠️ 注意：所有请求都需要提供有效的 API 密钥进行身份验证

非流式请求

curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nono",
    "messages": [
      {"role": "user", "content": "What is artificial intelligence?"}
    ],
    "stream": false
  }'

流式请求

curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: Bearer your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nono",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ],
    "stream": true
  }'

带系统提示的请求

curl -X POST http://localhost:3601/chat/completions \
  -H "Authorization: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nono",
    "messages": [
      {"role": "system", "content": "You are a helpful research assistant."},
      {"role": "user", "content": "Tell me about renewable energy"}
    ]
  }'

🐳 Docker 部署

PerBridge 提供了完整的 Docker 支持，便于容器化部署。

拉取镜像

# 从Docker Hub 拉取 Docker 镜像
docker pull zhang157686/perbridge

也可以自己构建镜像：docker build -t perbridge .

运行容器

基本运行

docker run -d \
  --name perbridge \
  -p 3601:3601 \
  -e PERPLEXITY_API_KEY=your_secret_api_key_here \
  -e PERPLEXICA_API_URL=http://host.docker.internal:3000 \
  zhang157686/perbridge

完整配置运行

docker run -d \
  --name perbridge \
  -p 3601:3601 \
  -e PERPLEXITY_API_KEY=bbaa61035h9f3592p3d7cb995000a67e \
  -e PERPLEXICA_API_URL=https://your-perplexica.com \
  -e FOCUS_MODE=webSearch \
  -e OPTIMIZATION_MODE=speed \
  -e CHAT_MODEL_JSON='{"provider": "openai", "name": "gpt-4"}' \
  -e EMBEDDING_MODEL_JSON='{"provider": "openai", "name": "text-embedding-3-large"}' \
  -e PLACEHOLDER_MODEL_NAME=nono \
  -e LOG_LEVEL=info \
  -e CORS_ORIGIN=* \
  -e HOST=0.0.0.0 \
  zhang157686/perbridge

健康检查

Docker 容器包含内置的健康检查：

# 检查容器健康状态
docker ps

# 查看健康检查日志
docker inspect --format='{{json .State.Health}}' perbridge

🔧 故障排除

常见问题

1. 连接 Perplexica 失败

症状：收到 ECONNREFUSED 或连接超时错误

解决方案：

确认 Perplexica 服务正在运行
检查 PERPLEXICA_API_URL 配置是否正确
如果使用 Docker，确保网络配置正确

# 测试 Perplexica 连接
curl http://your-perplexica-url/api/search

2. JSON 配置解析错误

症状：模型配置相关错误

解决方案：

确保 JSON 格式正确
使用单引号包围 JSON 字符串
验证 JSON 格式：

# 验证 JSON 格式
echo '{"provider": "ollama", "name": "llama3"}' | jq .

3. 端口冲突

症状：EADDRINUSE 错误

解决方案：

更改 PORT 环境变量
或停止占用端口的其他服务

# 查找占用端口的进程
lsof -i :3601  # Linux/macOS
netstat -ano | findstr :3601  # Windows

4. CORS 错误

症状：浏览器中出现跨域错误

解决方案：

设置正确的 CORS_ORIGIN 值
对于开发环境，可以使用 *

调试模式

启用详细日志以便调试：

# 设置调试日志级别
export LOG_LEVEL=debug
npm start

性能优化

1. 生产环境配置

NODE_ENV=production
LOG_LEVEL=warn
OPTIMIZATION_MODE=speed

2. 速率限制调整

# 增加速率限制（谨慎使用）
RATE_LIMIT_WINDOW_MS=3600000
RATE_LIMIT_MAX_REQUESTS=10000

📁 项目结构

PerBridge/
├── src/
│   ├── app.js                    # Express 应用配置
│   ├── server.js                 # 服务器启动文件
│   ├── config/
│   │   └── index.js              # 配置管理
│   ├── controllers/              # 控制器（预留）
│   ├── middleware/               # 中间件（预留）
│   ├── routes/
│   │   └── chat.js               # 聊天 API 路由
│   ├── services/
│   │   ├── httpClient.js         # HTTP 客户端服务
│   │   ├── requestTransformer.js # 请求格式转换
│   │   ├── responseTransformer.js# 响应格式转换
│   │   └── streamProcessor.js    # 流处理服务
├── Dockerfile                    # Docker 构建文件
├── package.json                  # 项目依赖配置
├── env.example                   # 环境变量示例
└── README.md                     # 项目说明文档

🛠️ 技术栈

Node.js - JavaScript 运行时
Express.js - Web 应用框架
Axios - HTTP 客户端
Helmet - 安全中间件
CORS - 跨域资源共享
dotenv - 环境变量管理

📊 API 文档

端点概览

方法	路径	描述
`GET`	`/`	获取服务基本信息
`GET`	`/health`	健康检查
`POST`	`/chat/completions`	聊天完成（兼容 Perplexity API）

响应格式

PerBridge 完全兼容 Perplexity API 的响应格式：

非流式响应

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "nono",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能（AI）是计算机科学的一个分支..."
      },
      "finish_reason": "stop"
    }
  ]
}

流式响应 (SSE)

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"nono","choices":[{"index":0,"delta":{"content":"人工"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"nono","choices":[{"index":0,"delta":{"content":"智能"},"finish_reason":null}]}

data: [DONE]

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

Fork 项目仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

开发环境设置

# 克隆您的 fork
git clone https://github.com/yourusername/perbridge.git

cd perbridge

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

📄 许可证

本项目采用 MIT 许可证。详情请见 LICENSE 文件。

🔗 相关链接

Perplexica - 开源搜索 AI 引擎
Perplexity AI - 商业搜索 AI 服务
@ai-sdk/perplexity - Perplexity AI SDK
Vercel AI SDK - AI 应用开发工具包

💬 支持

如果您遇到问题或有疑问：

查看故障排除部分
搜索 Issues
创建新的 Issue 描述您的问题

⭐ 如果这个项目对您有帮助，请给我们一个星标！

Made with ❤️ by the PerBridge

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
env.example		env.example
package-lock.json		package-lock.json
package.json		package.json

License

zhang157686/perbridge

Folders and files

Latest commit

History

Repository files navigation

PerBridge

📖 项目概述

🏗️ 架构原理

🚀 快速开始

前置要求

安装步骤

⚙️ 配置详解

🖥️ 服务器配置

🔗 Perplexica 连接配置

🤖 模型配置

聊天模型配置

嵌入模型配置

🎭 Perplexity API 兼容性配置

🔒 安全配置

🔐 API 密钥验证

📝 日志配置

📋 完整配置示例

🎯 使用方法

在现有应用中使用

直接 HTTP 请求

非流式请求

流式请求

带系统提示的请求

🐳 Docker 部署

拉取镜像

运行容器

基本运行

完整配置运行

健康检查

🔧 故障排除

常见问题

1. 连接 Perplexica 失败

2. JSON 配置解析错误

3. 端口冲突

4. CORS 错误

调试模式

性能优化

1. 生产环境配置

2. 速率限制调整

📁 项目结构

🛠️ 技术栈

📊 API 文档

端点概览

响应格式

非流式响应

流式响应 (SSE)

🤝 贡献指南

开发环境设置

📄 许可证

🔗 相关链接

💬 支持

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages