# QA-Engine

**Repository Path**: free4inno-team/qa-engine

## Basic Information

- **Project Name**: QA-Engine
- **Description**: 生成式对话引擎-业务控制模块
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-26
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 问答引擎

面向企业级知识库问答的 RAG（Retrieval-Augmented Generation）服务，支持多租户应用管理、LLM/Embedding/Rerank 插拔配置、Chroma 向量库检索、问答缓存，以及加盐哈希 + RSA 的 API Key 安全体系。本文档帮助你在裸机或 Docker 环境中完成部署。

---

## 功能概要
- 自定义应用：针对不同业务配置 Prompt、TopK、是否启用重排序/缓存。
- 模型接入：支持 OpenAI Chat、通义千问向量、通义重排序（可扩展自定义实现）。
- 知识库：与 ChromaDB 对接，提供集合/文档的增删改查与检索。
- 安全体系：API Key 中间件支持 RSA 解密与权限校验，新增管理员/用户登录接口（单次盐 + SHA256 challenge-response）并返回 JWT。
- 防护能力：登录接口具备 IP 限流，salt 一次性使用，支持 Special API Key。

---

## 环境要求
- Go 1.21+（用于编译后端）
- Docker / Docker Compose（可选，用于容器化部署）
- SQLite（项目默认使用 `QA-engine.db`，随仓库提供）
- ChromaDB（向量数据库，需要独立运行：Docker 镜像 `chromadb/chroma`）

### 启动 Chroma（开发调试）
```bash
docker pull chromadb/chroma
docker run -d --name chroma \
  -e ALLOW_RESET=TRUE \
  -p 8000:8000 \
  chromadb/chroma
```

后端通过 `-chroma-url` 与 `-chroma-token` 参数接入该实例。

---

## 配置说明
主配置位于 `config.yaml`，可通过 `-config` 参数覆写，关键字段如下：

| 字段 | 说明 |
| --- | --- |
| `special_api_key` | 特殊万能 Key，可跳过数据库校验（可留空） |
| `jwt_secret` / `jwt_issuer` / `jwt_expire_hour` | 登录后发放的 JWT 设置 |

> SQLite 文件 `QA-engine.db` 已随仓库提供，首次启动会自动迁移 `app/api_key/llm/embedding/rerank` 等表，可按需预置数据。

---

## 本地运行（Go 直接启动）
1. 安装依赖
   ```bash
   go mod tidy
   ```
2. 启动 Chroma（参考上文）。
3. 运行服务（Windows 示例）：
   ```bash
   go run ./cmd/app \
     -config ./config.yaml \
     -addr 0.0.0.0:8080 \
     -chroma-url http://127.0.0.1:8000 \
     -chroma-token your-chroma-token
   ```
   - `-addr`：监听地址与端口。
   - `-chroma-url`：Chroma HTTP 地址。
   - `-chroma-token`：若 Chroma 启用了鉴权则填写，否则留空。

访问 `http://localhost:8080` 即可调用 `/login`、`/chat` 等接口。

---

## 构建独立二进制
仓库 `app/` 目录包含现成的 Windows/Linux 可执行文件，若需要自行编译：

```bash
# Windows
go build -o app/qa-engine-windows-amd64.exe ./cmd/app

# Linux (容器使用该版本)
SET GOOS=linux
SET GOARCH=amd64
go build -o app/qa-engine-linux-amd64 ./cmd/app
```

---

## 使用 Dockerfile 部署
`Dockerfile` 结构极简，需要将目标平台的二进制与配置文件一起 COPY 进镜像：

```dockerfile
FROM alpine:latest
ARG ARCH_TYPE
COPY ./app/qa-engine-$ARCH_TYPE /app/qa-engine
COPY config.yaml /config.yaml
ENTRYPOINT ["/app/qa-engine"]
```

### 1. 准备二进制
```bash
GOOS=linux GOARCH=amd64 go build -o app/qa-engine-linux-amd64 ./cmd/app
```

### 2. 构建镜像
```bash
docker build -t qa-engine:latest \
  --build-arg ARCH_TYPE=linux-amd64 .
```

### 3. 运行容器
建议把配置与数据库挂载到宿主机，方便热更新：
```bash
docker run -d --name qa-engine \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/config.yaml \
  -v $(pwd)/QA-engine.db:/QA-engine.db \
  qa-engine:latest \
  -addr 0.0.0.0:8080 \
  -chroma-url http://host.docker.internal:8000 \
  -chroma-token your-chroma-token
```

> - `host.docker.internal` 适用于 macOS/Windows Docker Desktop；Linux 可换成宿主机 IP。
> - 如果 Chroma 部署在同一集群，可将 `-chroma-url` 指向容器网络内的服务名。

---

## 常用接口自检
- `GET /login/salt`：获取一次性盐。
- `POST /login/admin` & `/login/user`：挑战响应登录，返回 JWT。
- `POST /chat`：携带 `X-API-KEY`（可为 RSA 加密串）发起问答。
- `POST /document` / `/document/delete`：维护知识文档。
- `POST /embedding` / `/llm` / `/rerank`：注册模型服务。

若要验证 RSA 解密是否生效，可使用仓库中 `pkg/util/crypto/rsa.go` 内嵌的私钥配套的公钥，在本地对 API Key 做加密，再将 Base64 字符串放入 `X-API-KEY` Header。

---

## 故障排查
- **无法连接 Chroma**：确认 `-chroma-url` 可访问，并检查容器间网络或防火墙。
- **登录频繁被限流**：`middleware.RateLimitMiddleware(0.5, 5)` 意味着 2 秒补充 1 个令牌、突发桶深 5，请减少并发或调大参数。
- **提示盐值无效**：`/login/salt` 返回的 `salt_id` 仅能使用一次，请在 60 秒内立即发起登录请求。

如需进一步自定义部署（k8s/CI 等），可基于上述构建步骤扩展。欢迎在 `pkg` 目录中添加自定义的 LLM、Embedding、Rerank Provider 或安全策略。