# AgentSwap 新增 App 功能产品需求文档

我想了想逻辑上并不复杂，但 Gradio 的部署有必要抽成一个 service，和 CivitAI 的那套后端逻辑是分离的。而且第一版只要逻辑跑通就行。所以我这里列一个具体的计划。

### App 概念实现

首先，什么是 AgentSwap 的 App（当前迭代，我挑最好理解的说）：

1. 它是一个基于 Large Language Model(LLM) 的 prompt，帮你解决某个特定问题。
2. 它有一个 URL，点击会跳转到前端 UI，你可以在这个 UI 操作这个 App 对模型发起 prompt。这个 UI 应该是 Python 生成的 Gradio 最简单启动。
3. 模型并不和前端 UI 跑在一起。前端对该模型的后端（可以在任何地方，比如 Huggingface 提供免费的 API 请求）发起调用。

以上是一个很好理解的功能，在我们的产品里有 prompt 可以直接在对应的模型上跑，由外部服务提供商部署这个模型，我们发起远程调用。


例如，这个 prompt 帮你选择午饭吃啥。

------

以上没什么问题，但我们还有一个 charge token 的功能。这项服务的使用者应该付费。我们作为平台抽成、再打钱给作者。

所以，基于上述我们做一个修改就好了：

3. 模型并不和前端 UI 跑在一起。~~前端(gradio)对该模型的后端（可以在任何地方，比如 Huggingface 提供免费的 API 请求）发起调用。~~
前端(gradio)对我们 AgentSwap 的后端发起调用，打钱+请求后端干活。
4. 我们的后端对该模型的后端（可以在任何地方，比如 Huggingface 提供免费的 API 请求）发起调用。

换掉了一步在最后面。做了同样的事情。

### 前端服务是什么

我没有提前端 UI 是什么，但在步骤里提到了 "gradio"。这是 Python 生成的前端。比如 Stable Diffusion。

Gradio 一般用来跑本机的项目，但它也可以运行外部项目。比如说[这个项目](https://huggingface.co/spaces/ysharma/ChatGPT4/tree/main)只有一个文件，但如果[打开它的预览页](https://huggingface.co/spaces/ysharma/ChatGPT4)，诶它就能用。就很神奇。

所以我们让用户写好这个 `app.py`，我们帮忙装好依赖，运行起来就行了。

### 前端服务怎么区分/部署

### 区分

见下小节。用户侧按 `id` 区分。

### 部署

这里 @Garfield550，我想把这部分工作分给她。这一小节可以当作独立的文档来看。

目前的需求是，需要一个服务(service)：

> 输入：一个 GitHub Repo 的 URL，一个 id
> 输出：任务接受/任务不符合需求
>
> 副作用：将 Repo clone 下来，部署到某个地方但要能从 `app.agentswap.com/{id}` 访问到这个 gradio 项目的前端界面。
>
> 最方便的就是本机起一个 WebServer，目前只有个位数，都不用担心端口不够用的问题。
> 隔离可选 docker 或 python-venv

这个服务大概需要通知 AgentSwap 这个站点起好了，但不着急。反正有页面了就是起好了。

总结一下工作流：

1. (Node.js) API 处理请求，Clone GitHub 项目，`pip install -r requirements.txt`
2. 创建 Dockerfile，打包 Docker，启动 Docker（比如现在 4444 端口跑着新的 gradio 项目）
3. 修改 Webserver 配置文件（比如 caddy 的 Caddyfile，用正则替换或者 split by lines 都可以）
重启这个 Webserver

Caddyfile 例子：

app.agentswap.com {
  handle_path /1 {
    reverse_proxy 127.0.0.1:4444
  }
  handle_path /2 {
    reverse_proxy 127.0.0.1:4445
  }
}

`/1` `/2` 是 app 的 ID，能被 `app.agentswap.com/1` 访问到。

`handle_path` 命令会让实际请求的时候忽略掉位置参数。所以访问到的是 `127.0.0.1:4444` 而不是 `127.0.0.1:4444/1`

需要一个存储（文件、数据库）记录一下哪个端口被用掉了。

这是一个本机启动 App Docker Container 并能被外网正确访问的工作流。后续我们可能托管一个云服务来做这个事情。也就不用考虑端口、webserver 的问题了。

所以这个策略越简单越好，后续 POC 跑起来之后我们再重构它。

### 模型服务怎么区分/部署

### 区分
我们数据库里做记录，到时候知道哪个 prompt 用的啥就行了。我会改动 Civitai 的后端，给模型加上 App 相关字段。

interface ModelApp {
  id: number
  url: string
  name: string
}

`name` 创建前端/模型之后方便以后的用户选择。同时区分了后端去哪儿调用这个模型。
`id` 方便访问到。用户侧区分不同前端和模型。
`url` 对应 GitHub 前端 repo。

举例，我们现在有一个 ChatGLM 的 App：

id: 1
url: https://github.com/someone/chatglm-gradio-agentswap
name: ChatGLM

那我们有一个对应的后端 JSON 文件，记录了去哪儿生成一条 ChatGLM 的请求。这个请求地址的调用发生在上文介绍里的第四步了。

{
  "name": "ChatGLM",
  "endpoint": "https://api.huggingface.co/THUDM/chatglm-6b"
}

可以看到，AgentSwap 后端我把**前端UI**与**模型请求**写在一起了（都在 ModelApp）。我觉得对于 AgentSwap 而言，都是一个 App 的相关信息。

我们写前端的时候不需要太在意 `key` 填什么和 `endpoint` 从哪儿加，以后有别的模型再管。

> 虽然我猜 endpoint 写在前端 UI 的 GitHub repo 里。如果我和岛岛的思维完全对上了的话。

### 部署

模型侧（how endpoint works）不管，目前只用 ChatGLM。HuggingFace 有现成的。

但调用模型侧（how to call the endpoint）的具体参数应该有某处定义

> 如上所猜，大概也在 GitHub Repo 里

然后，

1. 我们需要改动一下 gradio 的功能，让它能调用到我们的后端 API
2. 这个后端 API 一但被正确调用，就带着具体参数去请求 endpoint，并返回那边给到的结果。

这段要改 CivitAI 的后端，但我感觉这里可以很后面，而且工作量不超过一两天。
> 所以暂时当没这个事，后面再考虑。