admin/aiagent
1
0
Fork 0
Code Issues 14 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
beff3fac8d153e77295c6ea79a76209e9f7bf03d
aiagent/docs/faq.md
renjianbo beff3fac8d fix: delete agent 500 error + dynamic personality + deployment guide 
- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions,
  schedules, executions, team_members) and unbind goals/tasks before delete
- Remove hardcoded personality templates in Android, replace with dynamic
  system prompt generation from name + description
- Set promptSectionsEnabled=false to bypass PromptComposer for personality
- Add Tencent Cloud Linux deployment guide (Docker Compose)
- Accumulated backend service updates, frontend UI fixes, Android app changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-29 01:17:21 +08:00

8.6 KiB
Raw Blame History

❓ 常见问题 FAQ

Frequently Asked Questions — 天工智能体平台使用中的常见问题与解答

一、通用问题

Q1: 天工智能体平台是什么？

天工是一个 AI Agent 搭建与工作流编排平台。你可以用它创建专属的 AI 数字员工，通过可视化拖拽设计工作流，让 Agent 调用工具自动完成任务。

Q2: 平台收费吗？

目前为社区版，免费使用。商业化版本（专业版/企业版）规划中，将提供多租户、高级监控等增强功能。

Q3: 支持哪些 LLM 模型？

支持 OpenAI (GPT-4o)、DeepSeek (V3/R1)、Anthropic (Claude Opus/Sonnet/Haiku) 及兼容 OpenAI API 格式的其他模型。在 Agent 配置中可自由选择和切换。

Q4: 数据安全吗？

  • 数据库连接支持 SSL/TLS
  • JWT 认证 + 密码哈希存储
  • API 速率限制保护
  • 安全响应头 (HSTS/X-Frame-Options/X-XSS-Protection)
  • 危险工具需人工审批 (HITL)

二、Agent 相关

Q5: 如何创建一个好的 Agent？

见《最佳实践指南》。核心要点：明确的角色描述 + 合适的工具集 + 清晰的工作流设计 + 充分的测试。

Q6: Agent 状态一直显示"草稿"怎么办？

点击 Agent 设计器中的「部署」按钮，Agent 将依次经过：草稿 → 发布中 → 已发布。

Q7: 已部署的 Agent 可以修改吗？

可以。修改后需要重新部署。旧版本会自动保存为工作流版本，可在版本管理中回滚。

Q8: Agent 执行到一半卡住了？

  1. 检查执行记录中的节点日志
  2. 查看 LLM API 是否配额耗尽或超时
  3. 检查工具调用是否有循环依赖
  4. 查看 Celery Worker 日志确认任务是否正常消费

Q9: 为什么看不到"使用"按钮？

只有状态为「已发布」或「运行中」的 Agent 才显示使用按钮。草稿状态的 Agent 只有创建者可以在设计器中测试。

Q10: 一个用户可以创建多少个 Agent？

无数量限制。

Q11: Agent 如何记住之前的对话？

在 Agent 配置中开启「启用记忆」，设置记忆范围（个人/团队）。Agent 会将对话精简压缩存入向量数据库，下次对话时自动检索相关记忆。

Q12: Agent 间能共享知识吗？

同一团队的 Agent 可以通过「团队记忆」共享知识。启用后，一个 Agent 学到的内容可以被同团队其他 Agent 检索使用。

三、工作流相关

Q13: 工作流节点有哪些类型？

触发器、LLM 节点、工具节点、条件分支、循环节点、子工作流、评估器、编排器、输出节点。详见《用户使用手册》第四章。

Q14: 如何让 LLM 节点引用上游输出？

在提示词模板中使用 {{变量名}} 语法。例如：{{trigger.output}} 引用触发器的输出，{{node_1.result}} 引用节点1的结果。

Q15: 工作流可以嵌套吗？

可以。使用「子工作流」节点调用另一个工作流，支持输入映射和深度保护（防止无限递归）。

Q16: 多个分支可以并行执行吗？

可以。DAG 工作流的多分支通过 asyncio.gather 并发执行，无依赖关系的节点同时运行。

Q17: 节点执行失败会自动重试吗？

在工作流编辑器中选中节点，配置「重试策略」：最大重试次数、重试间隔、错误处理方式（重试/通知/停止）。

Q18: 如何调试工作流？

  1. 使用「节点测试」功能单独测试每个节点
  2. 查看执行记录的节点级日志（输入/输出/耗时）
  3. 使用评估器节点验证输出质量

Q19: 工作流版本如何管理？

每次保存工作流自动生成版本。在版本管理中可查看历史版本、对比差异、回滚到任一历史版本。

四、知识库相关

Q20: 支持哪些文档格式？

PDF、TXT、Markdown、Word (.docx)、Excel (.xlsx)、HTML、CSV。

Q21: 文档上传后多久能被检索到？

上传后自动切片和向量化，通常在 30 秒内完成。大文档可能需要 1-2 分钟。

Q22: 知识库能存多少文档？

取决于向量数据库容量。建议单个知识库不超过 10,000 个文档，单个文档不超过 50MB。

Q23: RAG 检索不准怎么办？

  1. 确保文档内容清晰结构化
  2. 拆分过大的文档为多个小文档
  3. 使用更精确的系统提示词引导 Agent 如何使用检索结果

Q24: 知识会自动更新吗？

会。Celery Beat 定时任务每小时从 Agent 对话中提取新知识点自动入库，形成知识进化闭环。

五、账号与权限

Q25: 默认账号密码是什么？

默认管理员：admin / 123456

⚠️ 生产环境请第一时间修改默认密码。

Q26: 忘记密码怎么办？

联系管理员重置密码。自助找回密码功能规划中。

Q27: 如何创建新用户？

当前版本通过注册接口创建：POST /api/v1/auth/register。管理后台用户管理界面规划中。

Q28: 权限级别有哪些？

目前支持：管理员（admin）和普通用户（user）。多租户的 workspace_admin / member 角色规划中。

六、API 与集成

Q29: 如何通过 API 调用 Agent？

# 1. 登录获取 token
curl -X POST http://localhost:8038/api/v1/auth/login \
  -d "username=admin&password=123456"

# 2. 通过 agent-chat 接口对话
curl -X POST http://localhost:8038/api/v1/agent-chat/bare \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"message": "你的问题"}'

详细 API 文档见：/docs (Swagger UI) 或 /redoc。

Q30: 支持哪些认证方式？

JWT Bearer Token。登录获得 access_token，在请求头中携带 Authorization: Bearer <token>。

Q31: API 有限流吗？

有。登录接口 5 次/分钟，Webhook 接口 60 次/分钟，其他接口默认 120 次/分钟。

Q32: 飞书 Bot 如何配置？

参见《飞书智能体配置手册》(docs/飞书智能体配置手册.md)。

七、部署运维

Q33: 最低服务器配置要求？

  • 开发环境：2 核 CPU / 4 GB 内存 / 20 GB 磁盘
  • 生产环境：8 核 CPU / 16 GB 内存 / 100 GB SSD

Q34: 支持哪些部署方式？

  1. Docker Compose 一键部署（推荐）
  2. 手动安装（Python + Node.js）
  3. Kubernetes（规划中）

详见《部署与运维指南》。

Q35: 如何备份数据？

  • 数据库：使用腾讯云自动备份 或 mysqldump 每日备份
  • 配置文件：.env 文件纳入 Git 私有仓库管理
  • 详见 install.sh / upgrade.sh / uninstall.sh 脚本

Q36: 如何升级版本？

运行 upgrade.sh 脚本，自动完成：备份 → 拉取新镜像 → 滚动重启服务 → 清理旧镜像。

Q37: 日志在哪里查看？

  • API 日志：backend/logs/app.log（自动轮转，保留 30 天）
  • Docker 日志：docker-compose logs -f
  • Celery 日志：Worker 标准输出
  • 系统日志：前端「系统日志」页面

八、故障排查

Q38: 前端页面空白或加载失败？

  1. 检查后端 API 是否正常：访问 /health 端点
  2. 检查浏览器控制台是否有 CORS 错误
  3. 确认 Vite 代理目标端口正确（默认 8038）

Q39: API 返回 502 Bad Gateway？

后端服务未启动或已崩溃。检查：

docker-compose ps backend
docker-compose logs backend

Q40: 数据库连接失败？

  1. 检查 .env 中 DATABASE_URL 是否正确
  2. 确认数据库服务器网络可达
  3. 检查防火墙是否放行数据库端口

Q41: LLM 调用返回超时或错误？

  1. 检查 API Key 是否有效且配额充足
  2. 检查网络是否能访问 LLM API 地址
  3. 尝试切换模型或配置 Fallback LLM
  4. 增大工具超时时间

Q42: Celery Worker 不消费任务？

  1. 确认 Redis 是否正常运行
  2. 检查 Worker 是否启动：celery -A app.core.celery_app worker --loglevel=info
  3. 检查任务队列是否有积压

Q43: Agent 说"没有可用工具"？

  1. 检查 Agent 配置中是否启用了工具
  2. 检查 /health 端点确认内置工具已注册（56 个）
  3. 重启 Celery Worker 确保工具引导完成

九、其他

Q44: 可以在移动端使用吗？

可以。访问 /mobile-chat 路径使用移动端优化版。支持 PWA 安装到手机桌面，以及语音输入/播报。

Q45: 支持哪些语言？

平台界面为中文，Agent 对话支持任意语言（取决于 LLM 模型能力）。

Q46: 有视频教程吗？

规划中。目前可参考《用户使用手册》和《快速开始指南》。

Q47: 如何反馈问题或建议？

  • 提交 GitHub Issue
  • 联系平台开发团队
  • 在飞书 Bot 中反馈

最后更新：2026-06-14 | 适用版本 v1.0+

Reference in New Issue View Git Blame Copy Permalink