Octopus 产品文档

产品概述

Octopus 是一款面向企业的 AI 智能助手平台，将大语言模型的能力以产品化的形式赋能给团队中的每一个人。平台名取自章鱼 —— 多条触手同时工作，象征着平台同时覆盖对话、Agent、知识库、工作流等多种 AI 应用场景的能力。

核心能力矩阵

产品优势

• 轻量即用 — 无需 MySQL、Redis、消息队列等外部依赖，单命令启动，分钟级完成部署
• 模型无关 — 兼容任何 OpenAI 接口标准的模型服务，可对接公有云或私有部署模型
• 全链路流式 — 对话、Agent 推理、工作流执行全部支持 SSE 实时输出
• 数据自主 — 所有数据本地存储，满足金融、医疗、政务等行业的安全合规要求
• 开箱即用 — 预置常用工具和提示词模板，首次启动即可投入使用
• MCP 协议支持 — 原生支持 MCP JSON-RPC 2.0，可扩展对接飞书等企业服务

快速开始

只需几步即可在本地启动 Octopus 平台，开始使用全部功能。

环境要求

安装与启动

git clone <仓库地址>
cd ai-assistant
pip install -r requirements.txt

cp .env.example .env

OPENAI_API_BASE=https://your-llm-api.com/v1
OPENAI_API_KEY=your-api-key

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

前端构建（生产环境）

开发阶段可直接使用预构建的前端。如需自行构建：

cd frontend
npm install
npm run build

构建产物会输出到 html/ 目录，由后端自动提供静态文件服务。

核心概念

在开始使用平台各项功能前，了解以下核心概念有助于你更好地理解产品设计理念。

对话（Conversation）

对话是用户与 AI 交互的基本单元。每次对话保存完整的消息历史，支持上下文窗口管理 —— 系统自动截取最近 N 条消息（可配置）发送给模型，确保在控制 Token 消耗的同时保持对话连贯性。首条消息后系统会自动生成对话标题。

Agent 智能体

Agent 是具备自主决策能力的 AI 实体。与普通对话的"一问一答"模式不同，Agent 会主动分析任务、选择并调用合适的工具、根据工具返回结果进行下一步推理，直到任务完成。整个推理过程中的每个步骤都会被完整记录。

知识库（Knowledge Base）

知识库是文档的集合容器。文档上传后经过自动化处理流水线：解析 → 分块 → 向量化 → 存储。查询时通过语义向量检索（而非简单关键词匹配）找到最相关的文档片段，再由 LLM 综合这些片段生成答案并标注出处。

工具（Tool）

工具是 Agent 可以调用的外部能力接口。Octopus 中的工具以 HTTP 请求模板的形式定义 —— 你可以将任何 REST API 封装为工具，Agent 会根据任务需要自主决定何时、如何调用它们。

工作流（Workflow）

工作流将多个步骤编排为自动化流程。支持 LLM 推理、工具调用、条件分支等节点类型，可通过定时调度或 Webhook 触发执行，适合处理规律性的自动化任务。

智能对话

智能对话是平台最基础也是使用最频繁的功能模块，提供流畅的多轮对话体验。

功能特性

• 流式输出 — 基于 SSE 实时推送生成内容，用户无需等待完整响应即可看到生成过程
• 上下文窗口 — 可配置的历史消息保留数量，在对话深度和 Token 消耗间取得平衡
• 自动标题 — 首次对话后由 LLM 自动生成简洁概要标题，方便历史检索
• 对话管理 — 支持创建、删除、切换多个对话，左侧面板展示完整历史列表
• 导入导出 — JSON 格式的对话数据导入导出，支持跨实例迁移
• 公开分享 — 一键生成无需登录即可访问的分享链接

使用方式

1. 进入平台，点击左侧导航栏的「对话」图标
2. 点击左上角「+」新建对话（或选择已有对话继续）
3. 在底部输入框输入消息，按 Enter 发送
4. AI 会以流式方式逐字输出回复

对话配置

Agent 智能体

Agent 智能体是平台最具创新性的能力。它不只是"对话"，而是一个能够自主思考、调用工具、分步完成复杂任务的智能助手。

工作原理

功能亮点

• 透明的推理过程 — 每个工具调用步骤的输入、输出、耗时都可展开查看
• 完整的历史记录 — Agent 对话和所有工具步骤都会持久化保存
• 灵活的工具配置 — 通过自定义工具模块添加任意 HTTP API 作为 Agent 能力
• 安全的执行环境 — 工具调用在服务端执行，参数经过模板化处理避免注入风险

典型使用场景

知识库 RAG

知识库模块实现了完整的检索增强生成（Retrieval-Augmented Generation）流程，让 AI 的回答基于你的私有文档，而非仅依赖模型训练数据。

文档处理流水线

智能检索与回答

用户提问后，系统执行以下流程：

1. 将用户问题向量化，在向量数据库中检索最相似的文档片段
2. 按相关性分数过滤低质量结果（可配置阈值）
3. 可选的 LLM 重排序 —— 用大模型对检索结果做二次精排
4. 将筛选后的文档片段作为上下文注入 Prompt
5. LLM 生成回答，并标注引用了哪些源文档的哪些段落

功能特性

• 多知识库隔离 — 按主题或部门创建独立知识库，数据完全隔离
• 文档摘要生成 — 上传后可用 AI 自动生成文档概要
• 出处精确引用 — 回答中标注来源文档名称和具体段落
• 飞书文档导入 — 配置飞书应用凭证后可直接导入在线文档
• 知识库对话 — 在知识库上下文中进行多轮连续对话
• 质量可衡量 — 统计面板展示检索命中率和相关性分数分布

配置项

工具与工作流

工具模块允许你将企业内部的任意 HTTP API 封装为 Agent 可调用的能力，工作流模块则将多个步骤编排为可自动执行的流程。

自定义工具

每个工具由以下要素组成：

工具管理

• 可视化创建 — 表单化配置工具各项属性，无需编码
• 在线测试 — 传入参数即可测试工具是否正常工作
• 启用/禁用 — 灵活控制 Agent 可使用的工具范围
• 导入/导出 — JSON 格式备份和跨实例迁移工具配置
• 预置工具 — 系统内置常用工具模板，首次启动自动加载

工作流引擎

将多个处理步骤编排为自动化流程：

• 触发方式 — 手动执行、Cron 定时调度、Webhook 外部回调
• 节点类型 — LLM 推理、工具调用、条件分支、数据映射与转换
• 执行监控 — 实时查看每个节点的执行状态、输入输出和耗时
• 错误处理 — 节点失败时支持重试、跳过或终止流程

提示词模板

提示词模板帮助团队将 AI 交互的最佳实践沉淀为可复用的标准化模板，降低使用门槛，提升输出质量。

适用场景

• 任务标准化 — 为翻译、摘要、代码审查等常见任务预设高质量 Prompt
• 团队共享 — 经过验证的提示词模板全团队共享，无需重复摸索
• 角色预设 — 为不同岗位定制专属 AI 助手人设（如法务助手、HR 助手）
• 变量注入 — 模板支持 {{变量名}} 占位符，使用时动态填充上下文

模板结构

名称：周报生成助手
描述：根据本周工作内容自动生成结构化周报
模板内容：
  你是一位专业的技术文档撰写者。请根据以下工作内容，
  生成一份结构化的周报，包含：本周完成、进行中、下周计划。

  本周工作内容：
  {{work_content}}

数据洞察

全面的使用统计面板，帮助你了解平台使用情况、评估 AI 效果、控制成本。Dashboard 为默认登录首页。

统计维度

分享协作

支持将对话成果安全便捷地分享给同事或外部人员。

分享方式

• 公开链接 — 一键生成无需登录的分享链接，对方可直接浏览完整对话内容
• 对话导出 — 将对话以 JSON 格式导出为文件，支持跨实例导入
• 知识库问答分享 — 分享 RAG 对话时同步展示引用的原文出处
• Agent 对话分享 — 完整展示 Agent 的工具调用步骤和推理过程

消息通知

实时事件推送系统，确保重要事件不被遗漏。通知在页面右上角实时弹出，也可在通知面板中查看历史记录。

通知类型

• 文档处理完成 — 知识库文档解析和向量化完成时通知
• 配额告警 — 使用量接近配额上限时预警
• 任务结果 — Agent 任务和工作流执行完成后通知
• 审批请求 — 工作流中需要人工审批的节点
• 系统公告 — 管理员发布的全局通知

通知管理

• 支持标记单条/全部已读
• 支持删除不需要的通知
• 未读计数实时更新，红点提醒
• 基于 SSE 实现，页面打开即自动连接，无需刷新

模型管理

统一管理接入平台的大语言模型，支持运行时动态切换，无需重启服务。

核心能力

• 模型池管理 — 查看所有已配置模型及其状态
• 运行时切换 — 一键切换当前使用的模型，立即生效
• 多 Key 轮转 — 配置多个 API Key 自动轮转，提升可用性和并发能力
• 配置热更新 — 修改 API 地址或密钥后自动重建客户端连接

兼容的模型服务

Octopus 兼容所有实现 OpenAI Chat Completions API 标准的模型服务：

用户与权限

基于业界标准的 JWT + RBAC 安全体系，保障平台访问安全和数据隔离。

认证机制

• JWT Token 认证 — 登录后获取 access token（短期有效）+ refresh token（长期有效）
• 无感刷新 — access token 过期后前端自动使用 refresh token 换取新 token
• 安全存储 — 密码采用 bcrypt 哈希存储，数据库中不保存任何明文密码
• 路由保护 — 除登录接口和公开分享外，所有 API 均需携带有效 Token

权限与配额

• 基于角色的访问控制（RBAC），按角色分配功能权限
• 使用配额管理 —— 按用户或团队维度设置 API 调用上限
• 配额用尽时系统自动阻止并发送告警通知
• 管理员可在 Dashboard 查看各用户的使用统计

系统设置

通过 Web 管理界面或 API 修改平台运行时配置，所有改动即时生效，无需重启服务。

设置管理方式

• Web 界面 — 登录后点击左侧「设置」面板，表单化修改各项配置
• API 接口 — 通过 GET/PUT /settings 接口程序化管理配置
• 环境变量 — 首次部署通过 .env 文件初始化配置

可配置项

• LLM API 地址与密钥
• 默认模型选择与模型列表
• 对话上下文窗口大小
• RAG 检索相关性阈值
• LLM 重排序开关
• 飞书应用集成凭证
• JWT Token 有效期
• 通知推送配置

架构总览

Octopus 采用前后端分离的分层架构，后端基于 Python FastAPI，前端为 Vue 3 SPA。各层职责清晰，松耦合设计便于扩展和维护。

系统架构图

┌─────────────────────────────────────────────────────┐
│                   前端 (Vue 3 SPA)                    │
│        对话 │ Agent │ 知识库 │ 工具 │ 统计 │ 设置      │
└────────────────────────┬────────────────────────────┘
                         │ HTTP / SSE
┌────────────────────────▼────────────────────────────┐
│                  API 网关 (FastAPI)                   │
│         认证 (JWT) │ 路由 │ 请求验证 (Pydantic)       │
├─────────────────────────────────────────────────────┤
│                    服务层 (Service)                   │
│  ChatService │ AgentService │ RAGService │ ...       │
├─────────────────────────────────────────────────────┤
│                    AI 层 (Intelligence)               │
│   LLMClient │ TaskAgent │ Retriever │ Embedder       │
├─────────────────────────────────────────────────────┤
│                  基础设施 (Infrastructure)             │
│        SQLite │ ChromaDB │ 文件存储 │ MCP Client      │
└─────────────────────────────────────────────────────┘

核心请求流

设计要点

• 单体但分层 — 通过清晰的层次划分获得微服务的可维护性，同时保持部署的简洁性
• 异步优先 — FastAPI + asyncio 提供高并发处理能力
• 零外部依赖 — SQLite + ChromaDB 嵌入式存储，不依赖外部数据库服务
• 热更新 — 核心组件（LLMClient、配置）支持运行时更新，无需重启

技术栈

后端技术

前端技术

API 概览

Octopus 提供完整的 RESTful API，涵盖平台所有功能。API 按模块组织，遵循统一的设计规范。

认证方式

除公开接口外，所有 API 请求需在 Header 中携带 JWT Token：

Authorization: Bearer <your-access-token>

API 模块一览

部署指南

Octopus 设计为极简部署 —— 无需外部数据库、消息队列或缓存服务。以下提供多种部署方式供选择。

方式一：直接部署

适合快速体验和小规模使用：

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 构建前端静态文件
cd frontend && npm install && npm run build && cd ..

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 API 地址和密钥

# 4. 启动服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

方式二：Docker 部署

适合生产环境，便于管理和迁移：

# 构建镜像
docker build -t octopus .

# 运行容器（挂载数据卷确保持久化）
docker run -d \
  --name octopus \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  --env-file .env \
  octopus

方式三：多 Worker 部署

高并发场景下使用多个 Worker 进程：

python -m uvicorn app.main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4

生产环境最佳实践

配置说明

所有配置通过 .env 文件管理，也可在部署后通过 Web 界面的设置页面动态修改。

完整配置项

最小化配置示例

# .env - 最小可用配置
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4o

升级与备份

数据备份

Octopus 的所有持久化数据集中在以下位置，备份时复制即可：

升级步骤

git pull origin main

pip install -r requirements.txt
cd frontend && npm install && npm run build && cd ..

常见问题

支持哪些大语言模型？

任何兼容 OpenAI Chat Completions API 接口标准的模型都可以接入，包括但不限于：OpenAI GPT 系列、智谱 GLM-4、通义千问 Qwen、DeepSeek、Ollama/vLLM 部署的开源模型。只需配置对应的 API 地址和密钥即可。

数据安全性如何保障？

Octopus 的所有数据（对话记录、知识库文档、用户信息）均存储在本地，不依赖任何第三方云存储服务。对外的唯一网络请求是 LLM API 调用。如需完全离线运行，可通过 Ollama 等工具在本地部署模型。

知识库支持多大的文档？

理论上没有硬性大小限制。大文档会被自动分块处理，处理时间与文档长度成正比。实测建议单个文档不超过 10MB（约 200-300 页 PDF），以获得最佳处理速度和用户体验。

如何对接飞书文档？

在系统设置中配置飞书应用的 App ID 和 App Secret，确保该应用拥有文档读取权限。配置完成后即可在知识库中通过飞书文档 URL 直接导入。系统会优先使用 MCP 协议导入，若 MCP 服务不可用则自动回退到飞书 Open API。

Agent 一次最多能调用多少次工具？

默认上限为每轮对话 5 次工具调用。这是为了防止 Agent 陷入无限循环。如果任务需要更多步骤，建议：拆分为多次对话交互，或优化工具粒度使单次调用覆盖更多操作。

支持多用户同时使用吗？

支持。FastAPI 基于 Python asyncio 异步架构，天然支持高并发。生产环境可通过 --workers 参数增加 Uvicorn 工作进程数量来提升并发处理能力。各用户数据通过认证体系完全隔离。

如何重置管理员密码？

如果忘记管理员密码，可删除 app.db 数据库文件后重启服务，系统会重新创建默认 admin/admin 账号。注意：这会清除所有数据，请务必提前备份。未来版本将提供命令行重置工具。

可以同时部署多个实例吗？

可以，但由于使用 SQLite 文件数据库，多实例不应共享同一个 app.db 文件。如需多节点部署，建议每个实例使用独立的数据目录，或等待未来版本对 PostgreSQL 的支持。

更新日志

v1.0 — 2025 年首个正式版

Octopus 平台正式发布，包含以下完整功能模块：

• 智能对话 — 多轮流式对话、上下文窗口、自动标题、对话历史管理
• Agent 智能体 — 多轮工具调用循环、推理步骤可视化、对话持久化
• 知识库 RAG — 文档解析、语义分块、向量检索、出处引用、LLM 重排序
• 自定义工具 — HTTP 模板定义、批量处理、在线测试、导入导出
• 工作流引擎 — 多节点编排、定时调度、Webhook 触发
• 模型管理 — 多模型动态切换、多 Key 轮转、配置热更新
• 提示词模板 — 可复用模板库、变量注入、团队共享
• 用户认证 — JWT 双 Token 认证、RBAC 权限、配额管理
• 数据洞察 — 多维度统计分析、趋势图表、RAG 质量评估
• 消息通知 — SSE 实时推送、未读管理
• 分享协作 — 公开链接分享、对话导入导出
• 飞书集成 — MCP + Open API 双通道文档导入