# NexusAI

**Repository Path**: solidify-the-foundation/nexus-ai

## Basic Information

- **Project Name**: NexusAI
- **Description**: 一个面向后端工程师转型 AI 工程化 / AI Infra / LLM App 的实战作品集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NexusAI

NexusAI 是面向 AI Infra / LLM App 工程能力的生产化练习场。当前仓库已经把 16 周计划的第一个纵向切片落成代码：OpenAI-compatible Go Gateway、Spring Boot RAG Engine、22 条 Golden QA、确定性检索门禁、可选 Ragas LLM-Judge 通道，以及本地可观测依赖栈。

## 架构

```mermaid
flowchart LR
    Client["Client / Agent"] --> Gateway["Go Gateway\nSSE · Rate Limit · Fallback · Token"]
    Gateway --> Ollama["Ollama / vLLM"]
    Client --> RAG["Java RagPipeline"]
    RAG --> Search["In-memory baseline\n→ Elasticsearch hybrid"]
    RAG --> Gateway
    Eval["Golden Dataset + Eval Suite"] --> RAG
    Eval --> Reports["Recall gate + Ragas reports"]
    Gateway --> Prom["Prometheus / Grafana"]
    RAG --> Prom
```

模块 interface 刻意保持小：Gateway 只承诺 OpenAI-compatible HTTP 语义；RAG Engine 只承诺 `POST /v1/rag/query` 与可追溯 Evidence。内部检索和生成 adapter 可以演进而不扩散复杂度。

## 5 分钟验证（不需要模型）

本机只需 Go 1.24+ 与 Python 3.11+：

```bash
make verify
```

该命令会运行 Gateway 单元测试、Python 评估测试和 Recall@5 门禁，并写入 `eval-suite/reports/baseline.json`。当前基线来自真实执行：22 条 QA、Recall@5 0.9545、MRR 0.9545。没有 JDK/Maven 时 Java 测试会明确跳过，并由 CI 或 Docker 执行。

## 启动完整本地栈

Apple Silicon 上先启动原生 Ollama；Docker Desktop 无法把 Metal GPU 暴露给 Ollama 容器，因此容器模式只适合作为 CPU/服务器备选。若 Ollama App 尚未运行，请先在另一个终端执行 `ollama serve`。

```bash
cp .env.example .env
make model-pull
make infra-up
make apps-up
```

服务地址：Gateway `http://localhost:8080`，RAG Engine `http://localhost:8081`，Elasticsearch `http://localhost:9200`，Prometheus `http://localhost:9090`，Grafana `http://localhost:3000`（`admin/nexusai`）。首次拉取 7B 模型需要较多磁盘和时间。需要容器 CPU 模式时运行 `make model-container-up model-container-pull`，并把 `.env` 中的 `NEXUSAI_MODEL_BACKEND_URL` 改为 `http://ollama:11434`。

验证聊天：

```bash
curl http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'X-Tenant-ID: demo' \
  -d '{"model":"qwen2.5:7b-instruct","messages":[{"role":"user","content":"用一句话解释 RAG"}]}'
```

验证 RAG：

```bash
curl http://localhost:8081/v1/rag/query \
  -H 'Content-Type: application/json' \
  -d '{"question":"哪些错误会触发模型 Fallback？","topK":5}'
```

## 评估工作流

```bash
make eval          # 纯向量基线，CI 必跑
make eval-hybrid   # 本地 BM25 + vector 对比
make eval-ragas    # 需要 RAG Engine、Ragas/openai Python 依赖与 Judge 模型
```

安装慢速通道依赖可使用 `python -m pip install -e 'eval-suite[ragas]'`。默认 Judge 使用 Ollama 的 OpenAI-compatible 地址，可通过 `JUDGE_BASE_URL`、`JUDGE_API_KEY`、`JUDGE_MODEL` 修改。Ragas 的当前官方 quickstart 同样推荐把数据集、实验和结果保存为可比较资产：<https://docs.ragas.io/en/stable/getstarted/quickstart/>。

## 下一步

完整逐周验收标准见 [16 周执行路线图](docs/ROADMAP.md)。当前最有价值的下一刀是 Week 2：把 Java 内存检索替换为 Elasticsearch BM25 + dense_vector adapter，并在现有 22 条数据上跑一次受控对比；数据太简单时先扩充困难集，不能靠挑样本制造 15% 提升。

关键决策：

- [ADR-0001：离线门禁 + Ragas 慢速通道](docs/adr/0001-ragas-evaluation.md)
- [ADR-0002：Gateway 与 RagPipeline 模块接口](docs/adr/0002-module-seams.md)
- [首份 Retrieval Baseline 量化报告](docs/evaluations/2026-07-31-retrieval-baseline.md)