p5js.ai 2 API

核心特性

• 双协议兼容 — 同时提供 /v1/messages（Anthropic）和 /v1/chat/completions（OpenAI）端点
• Tool Use 仿真 — 上游不支持原生 tool_use，本服务通过 XML 格式的 <function_calls> 提示词注入实现伪工具调用，并自动将响应中的 XML 解析回标准 tool_use / tool_calls 格式
• p5.js 噪声过滤 — 自动检测并剥离上游注入的 p5.js 助手问候语、前缀和尾缀
• SSE 修复 — 上游会输出畸形的 ddata: / ata: 前缀，本服务自动修正为标准 SSE 格式
• 双层缓存 — 内存缓存 + 可选 Redis 二级缓存，相同请求自动命中，流式/非流式共用同一份完成结果
• In-flight 合并 — 并发相同请求不会重复打上游，follower 等待 leader 结果
• 连接池复用 — 共享 httpx 异步连接池，适合高并发场景
• 代理支持 — 支持 UPSTREAM_PROXY_URL 或标准 HTTP_PROXY / HTTPS_PROXY 环境变量

项目结构

p5js/
├── main.py              # FastAPI 应用入口、路由定义
├── config.py            # 常量、环境变量、模型列表、正则模式
├── filters.py           # p5.js 噪声过滤、工具感知文本缓冲
├── tools.py             # Tool XML 提示词构建、解析、提取
├── translate.py         # 协议转换（Anthropic/OpenAI → 上游消息格式）
├── upstream.py          # 上游 HTTP 客户端、SSE 解析、实时捕获
├── render.py            # Artifact → Anthropic/OpenAI JSON/SSE 渲染
├── stream.py            # 实时流处理（带/不带工具，带缓存集成）
├── response_cache.py    # 双层缓存系统（内存 + Redis）
├── tests/               # 测试套件
│   ├── test_response_cache.py
│   └── test_filters.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── start.sh
├── .env.example         # 环境变量示例
└── README.md

快速开始

本地运行

./start.sh

首次运行会自动创建 venv 并安装依赖，然后在 http://127.0.0.1:18185 监听。

Docker 部署

# 直接构建
docker build -t p5js2api:latest .
docker run --rm -p 18185:18185 p5js2api:latest

# 或使用 docker compose（自带 Redis）
docker compose up -d --build

默认 compose 配置同时启动一个本地 Redis 实例，端口通过 P5JS2API_PORT 环境变量控制（默认 18185）。

支持的模型

接口一览

服务不校验 API Key，任意非空字符串均可通过认证。

使用示例

Claude Code（Anthropic 协议）

export ANTHROPIC_BASE_URL=http://127.0.0.1:18185
export ANTHROPIC_AUTH_TOKEN=dummy
export ANTHROPIC_MODEL=claude-opus-4-7
export ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

claude

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18185/v1",
    api_key="sk-dummy",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

第三方工具（Chatbox / NextChat / LobeChat / one-api / Cherry Studio 等）

• Base URL / API 地址: http://127.0.0.1:18185/v1
• API Key: 任意非空字符串（如 sk-dummy）
• 模型名: 填写上方「支持的模型」中的任一项

curl

# Anthropic 协议
curl http://127.0.0.1:18185/v1/messages \
  -H 'content-type: application/json' \
  -H 'x-api-key: dummy' \
  -d '{"model":"claude-sonnet-4-5","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}'

# OpenAI 协议
curl http://127.0.0.1:18185/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"hi"}]}'

缓存系统

服务默认启用完整响应缓存：

• 先走进程内内存缓存（LRU，默认 256 条）
• 配置 RESPONSE_CACHE_REDIS_URL 后升级为 内存 + Redis 双层缓存
• 相同请求并发命中 miss 时做 in-flight 合并，避免同时打爆上游
• stream=true 和 stream=false 共用同一份完成结果缓存

环境变量

完整环境变量列表见 .env.example，核心配置：

响应头

• X-Proxy-Cache: HIT | MISS | BYPASS | DISABLED
• X-Proxy-Cache-Source: memory | redis | inflight | live

跳过缓存

任一方式：

• 请求头 X-Proxy-Cache: bypass
• 请求头 Cache-Control: no-cache

代理配置

容器内支持两种代理方式：

• 显式设置 UPSTREAM_PROXY_URL
• 标准环境变量 HTTP_PROXY / HTTPS_PROXY / NO_PROXY

/health 里的 upstream.proxy_configured 会显示当前是否检测到代理配置。

工作原理

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Client      │────▶│  p5js.ai 2 API   │────▶│  p5js.ai    │
│ (Claude/     │◀────│  (this project)   │◀────│  upstream   │
│  OpenAI)     │     │                   │     │             │
└─────────────┘     └──────────────────┘     └─────────────┘
                    │  ├─ 协议转换          │
                    │  ├─ Tool XML 注入/解析 │
                    │  ├─ p5.js 噪声过滤    │
                    │  ├─ SSE 修复          │
                    │  └─ 双层缓存          │

1. 协议转换：将 Anthropic 或 OpenAI 格式的请求转换为 p5js.ai 上游格式（messages + provider + model + deviceId + sessionId）
2. Tool Use 仿真：将工具定义注入系统提示词为 XML 格式，将上游文本响应中的 <function_calls> XML 块解析回标准 tool_use / tool_calls
3. 噪声过滤：检测并剥离上游自动注入的 p5.js 助手问候语、标题、尾缀推荐
4. SSE 修复：上游输出的畸形 ddata: / ata: 前缀自动修正为标准 data:
5. 缓存：完整响应缓存，流式和非流式共用，支持 in-flight 合并

注意事项

• 上游 p5js.ai 会在没有 system 字段时注入 p5.js 助手提示词，客户端显式传 system（Anthropic）或 {"role":"system"} 消息（OpenAI）即可覆盖
• 流式缓存命中时会重新生成新的响应 ID / 时间戳，并按本地协议重新渲染
• 默认缓存上限 32 MiB，超过不会截断返回，只是跳过缓存，在 /health 的 cache.oversize_skips 可见
• 设 RESPONSE_CACHE_MAX_ENTRY_BYTES=0 可取消上限
• 本服务依赖 p5js.ai 接口可用性，上游变更可能影响使用
• 仓库地址：https://github.com/xiaolajiaoyyds/p5jsAi