快速开始

#用户案例

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

#准备环境

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

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

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 复制模板。

#启动服务

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

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 查询邻居或路径。

#第一次 API 调用

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

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。

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}'

#验证结果

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