# 快速开始

启动服务并直接进入默认工作区，配置模型连接，使用内置示例或上传数据完成首次分析。

## 用户案例

- [观看用户案例](/zh/user-cases/): 科学智能：分子性质、环系与反应位点；金融风控：股权与控制关系；关系洞察：《天龙八部》人物社群与隐含关系。

运行工作台后，首页提供《天龙八部》、金融风控和化学分子性质分析三类内置示例。点击“使用示例图”进入对应会话；点击首页案例中的问题主题会加载预置图并直接发起分析，无需重新上传和构图。用户案例页面提供三类场景的任务说明与演示视频。

## 准备环境

以下命令在项目根目录执行，用于运行 iGraph 本身。推荐用 Docker Compose 管理项目的 Python 服务和 PostgreSQL；这个静态文档网站与应用服务独立运行。

- 安装支持 Compose 的 Docker；准备一个项目支持的模型供应商 API Key 与 Base URL。
- 复制 .env.example 并按其中的供应商配置块填写凭据；真实 .env 不应提交到版本控制。

```bash
cp .env.example .env
python -c "import secrets; print(secrets.token_hex(32))"
```

将生成的随机值填入 .env 的 IGRAPH_CONTROL_SERVICE_KEY。Backend、Agent Runtime 和 Graph Engine 的 HTTP/MCP 适配器必须使用同一个值，即使关闭 Run 取消功能也不能留空。Windows PowerShell 可用 Copy-Item .env.example .env 复制模板。

## 启动服务

```bash
docker compose up --build -d
docker compose ps
curl http://localhost:21108/health
```

| 入口 | Compose 访问地址 |
| --- | --- |
| 工作台和公共 API（宿主机） | http://localhost:21108 |
| Backend（仅容器网络） | http://backend:21109 |
| Graph Engine HTTP（仅容器网络） | http://graph-engine-api:21111 |
| Agent Runtime（仅容器网络） | http://agent-runtime:21112 |
| Graph Engine MCP（仅容器网络） | http://graph-engine-mcp:21110/mcp |

Compose 定义七个服务：frontend、backend、agent-runtime、graph-engine-api、graph-engine-mcp、graph-engine-worker 和 postgres。默认只有 frontend 的 21108 端口对宿主机开放，/api/* 由它转发给 Backend。graph-engine-worker 负责大图后台任务，没有 HTTP 健康检查，显示 running 即可；其他服务应等待健康检查通过。

单用户版默认仅将前端绑定到 127.0.0.1:21108（FRONTEND_BIND_ADDRESS / FRONTEND_PORT 可配置）。远程使用时通过 SSH 隧道或受控访问入口连接。IGRAPH_ADMIN_USER_ID 指定默认工作区归属，默认 admin；不需要创建或维护登录账号。

## 从界面完成第一次分析

- 打开工作台即可进入默认工作区，无需登录或注册。在“模型服务”中配置提供商连接和模型，再选择用于本次分析的模型。
- 进入“创建你的图”并选择“上传数据源”。单个文件可用 SQL、CSV 或 TXT；同时上传多个文件时，只能选择 CSV。
- 在构图页先看“源数据示例”。多表 CSV 需核对表名、表头、主键和外键；普通文本需选择逐行构图还是由模型抽取实体与关系。
- 发起构图，等待草稿生成，检查图规模、结构和版本，再点击“保存构图结果”。保存后状态变为 ready，才能用于分析；关闭构图窗口后，服务端会继续执行，可重新打开查看。
- 创建项目，在项目数据集入口选择“加载已构好的图”。导入独立副本后，在该项目中新建会话并选择数据集。
- 先提问“请确认当前数据集、图版本、节点数、边数和关系方向”，再根据真实节点 ID 查询邻居或路径。

- [继续阅读工作台操作指南](/zh/workspace/): 查看界面入口、结果核对方法、训练曲线、报告下载和记忆管理。

## 第一次 API 调用

公共 API 自动使用默认工作区，不需要客户端提供用户 ID 或登录令牌。先读取工作区信息，再创建会话。命令示例使用 Bash；PowerShell 请将 curl 替换为 curl.exe 并按其语法换行。

```bash
curl http://localhost:21108/api/workspace

curl -X POST http://localhost:21108/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"reasoning_mode":"direct","planning_mode":"auto"}'
```

从创建响应取出 session_id，再发送消息。模型名称可省略以使用默认配置；指定时使用当前工作区可用且连接已配置的模型。Accept-Language 指定本轮回复语言，示例使用 zh-CN，英文可用 en。

```bash
curl -N -X POST http://localhost:21108/api/sessions/SESSION_ID/chat/stream \
  -H "Accept-Language: zh-CN" \
  -H "X-iGraph-Stream-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{"message":"介绍可用的图分析能力","start_request_id":"31ac1101-cd5a-4b60-a2f7-d8379d934fe9","reasoning_mode":"direct","planning_mode":"auto","stream":true,"background":true}'
```

> **每条新消息使用新的请求标识**
> start_request_id 用于识别重复提交。同一条消息因网络失败重试时复用原值；发送新消息时生成新的 UUID。上面的固定值仅用于展示格式。

## 验证结果

- GET /api/workspace 应返回 valid: true、single_user: true，以及默认工作区归属和模型信息；这一步读取工作区状态，不执行登录。
- 会话创建返回 session_id；流式请求应逐步返回 text/event-stream 事件。
- 普通构图先生成草稿，保存后才有 ready 状态和可用于分析的 revision；会话加载后再用 get_graph_info 核对 graph_version 与图规模。上传成功或草稿生成不等于已经保存并加载。