# OCAI-Service

**Repository Path**: OpenCloudOS/ocai-service

## Basic Information

- **Project Name**: OCAI-Service
- **Description**: OCManager AI 能力后端服务，提供 LLM 推理、OS 知识库管理、RAG 检索增强与 LangGraph 编排能力。是 OCAI的"大脑"——处理自然语言理解、诊断推理链生成、知识检索与答案合成。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ocai-service

本 workspace 聚合 **ocai-service**（AI 对话 / 工具编排）与 **ops-mate**（监控诊断 Agent），用于联调与统一部署。

```
ocai-service/
├── README.md
├── LICENSE / NOTICE / SECURITY.md
├── CONTRIBUTING.md / CHANGELOG.md
├── config/                 # 统一部署配置（.env）← 配置入口
├── scripts/
│   └── start-ops-mate.sh   # 启动 diaglite + diagagent
├── ocai-service/           # Python FastAPI 服务
└── ops-mate/
    └── diaglite/           # Go：diaglite (:8787) + diagagent (:8788)
```

---

## 快速开始

### 1. 配置

```bash
cd ocai-service
cp config/env.example config/.env
# 或与 oc-manager 同机：
# ln -sfn ../../oc-manager/config/.env config/.env
$EDITOR config/.env
```

至少填写：`OCAI_JWT_SECRET`、`OCAI_LLM_DEFAULT_API_KEY`、MySQL/Redis（或共用 oc-manager 的 `MYSQL_*` / `REDIS_*`）。

### 2. 启动 ops-mate（监控诊断，可选但推荐）

完成下方 [ops-mate 配置](#ops-mate-配置) 后：

```bash
bash scripts/start-ops-mate.sh
```

在 `.env` 中设置 `OCAI_DIAGAGENT_BASE_URL` / `OCAI_DIAGLITE_BASE_URL` 后，ocai 对话里可使用 `diagnose_machine` 等工具。

### 3. 启动 ocai-service

```bash
# Docker（需 oc-manager infra 已就绪）
cd ocai-service && bash scripts/deploy.sh up

# 或本地
cd ocai-service && bash scripts/run.sh
```

---

## ops-mate 配置

ops-mate 由 **diaglite**（任务网关 / catalog / 内置 RAG）与 **diagagent**（多轮 LLM 诊断）组成，在宿主机以 Go 进程运行。与 ocai 集成的监控诊断路径**不需要** MySQL 或 Redis。

**依赖**：Go 1.22+、可用 LLM（可与 `OCAI_LLM_DEFAULT_*` 共用）；执行远程 preset（如 `io_quick`）时还需 **ansible** 与到目标机的 **SSH**。

### 1. diaglite：`ops-mate/diaglite/config.yaml`

首次启动时 `scripts/start-ops-mate.sh` 会从 `config.example.yaml` 生成；也可手动复制：

```bash
cd ops-mate/diaglite
cp config.example.yaml config.yaml   # 若尚未存在
```

主要字段：

| 字段 | 说明 |
|------|------|
| `listen` | 与 `OPS_MATE_DIAGLITE_PORT` 一致，默认 `:8787` |
| `ansible.user` / `private_key` / `port` | 全局 SSH，执行 preset 时使用 |
| `ansible.per_host` | 按 IP 覆盖 user / 端口 / 密钥 / 密码 |
| `ansible.inventory_groups` | 命名主机组，API 中传 `inventory_group` 批量下发 |
| `rag.index_paths` | 内置 RAG 语料目录（默认 `./corpus` 与 `../rag/Document/docs`） |

### 2. diagagent：`ops-mate/diaglite/diagagent.yaml`

```bash
cd ops-mate/diaglite
cp diagagent.example.yaml diagagent.yaml
```

主要字段：

| 字段 | 说明 |
|------|------|
| `listen` | 与 `OPS_MATE_DIAGAGENT_PORT` 一致，默认 `:8788`（启动脚本会覆盖 `-listen`） |
| `llm.base_url` / `model` | OpenAI 兼容网关，建议与 `OCAI_LLM_DEFAULT_HOST` / `NAME` 对齐 |
| `llm.api_key` | 建议留空，由环境变量注入（见下） |
| `diaglite.base_url` | 指向 diaglite，同机默认 `http://127.0.0.1:8787` |

### 3. 环境变量：`config/.env`

在 `config/env.example` 的 ops-mate 段追加或填写：

```bash
# 端口（与上述 yaml 的 listen 一致）
OPS_MATE_DIAGLITE_PORT=8787
OPS_MATE_DIAGAGENT_PORT=8788

# 远程 preset 时的 SSH（仅跑 preset 需要）
OPS_MATE_ANSIBLE_USER=ubuntu
OPS_MATE_ANSIBLE_PRIVATE_KEY=/path/to/id_rsa

# LLM：留空 DIAGAGENT_LLM_API_KEY 则复用 OCAI_LLM_DEFAULT_API_KEY
OCAI_LLM_DEFAULT_HOST=https://api.openai.com/v1
OCAI_LLM_DEFAULT_API_KEY=sk-xxx
DIAGAGENT_LLM_API_KEY=

# ocai-service 接入 ops-mate（非空才注册 diagnose_machine 等工具）
OCAI_DIAGLITE_BASE_URL=http://127.0.0.1:8787
OCAI_DIAGAGENT_BASE_URL=http://127.0.0.1:8788
```

### 4. 启动与验证

```bash
cd ocai-service
bash scripts/start-ops-mate.sh

curl http://127.0.0.1:8787/healthz   # ok
curl http://127.0.0.1:8788/healthz   # ok
```

### 5. ocai 容器访问宿主机 ops-mate

ocai-service 跑在 Docker 内时，`127.0.0.1` 指向容器自身，需改为宿主机可达地址：

| 场景 | `OCAI_DIAG*_BASE_URL` |
|------|------------------------|
| 同机 Linux | `http://172.17.0.1:8788` 或 `http://${SERVER_HOST}:8788` |
| compose 加 `extra_hosts` | `http://host.docker.internal:8788` |

更完整的变量说明与拓扑见 [config/README.md](config/README.md)。

---

## 组件与依赖

| 组件 | 技术 | 端口 | 外部依赖 |
|------|------|------|----------|
| **ocai-service** | Python / Docker | `OCAI_PORT`（默认 18000） | MySQL、Redis；可选 footstone、msg-etl、ops-mate |
| **diaglite** | Go | 8787 | SQLite（内嵌）；preset 需 ansible + SSH |
| **diagagent** | Go | 8788 | diaglite + OpenAI 兼容 LLM |
| **ops-mate/rag/** | Python | 无常驻服务 | 可选 DocRAGnizer 离线流水线；**ocai/diagagent 联调不需要** |

监控诊断最小链路：**diaglite + diagagent + LLM**；不需要 MySQL/Redis。RAG 默认索引 `diaglite/corpus/` 与 `ops-mate/rag/Document/docs`（OpenCloudOS 文档语料，BSD 3-Clause，见 NOTICE）。

---

## 文档

- 部署与变量详解：[config/README.md](config/README.md)
- 配置样例：[config/env.example](config/env.example)
- ocai-service API / 工具：[ocai-service/README.md](ocai-service/README.md)
- diaglite / diagagent HTTP API：[ops-mate/diaglite/docs/API.md](ops-mate/diaglite/docs/API.md)
- DocRAGnizer（可选离线流水线）：[ops-mate/rag/README.md](ops-mate/rag/README.md)

## 参与贡献

| 文档 | 说明 |
|------|------|
| [CONTRIBUTING.md](CONTRIBUTING.md) | 参与贡献流程 |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |

## 许可证

本仓库以 **GNU General Public License v2.0** 授权（见 [LICENSE](LICENSE)），与 [oc-manager](../oc-manager/LICENSE) 保持一致。第三方依赖与文档语料声明见 [NOTICE](NOTICE)（含 `ops-mate/rag/Document` 的 BSD 3-Clause 语料）。

## 安全

如发现安全问题，请按 [SECURITY.md](SECURITY.md) 说明私下反馈，勿在公开 issue 中披露细节。