跳转至

核心概念：API 服务

AI 服务基于 FastAPI，对外提供 REST + SSE + WebSocket 能力，主要用于：会话对话、Agent 管理、RAG 知识源管理、文档摄取与查询等。

文档定位

本页描述的是 API 服务在系统里的角色和运行边界，不是逐个接口字段的查表页。

如何选择：

  • 想看 API 在整体架构中的职责、数据流和运行约束：读本页
  • 想查所有 HTTP / SSE / WebSocket 路由：读 端点概览

  • 想看 FastAPI 应用对象和请求响应模型：读 API 参考 -> API 服务

  • SSE 流式回复（POST /stream）。

  • WebSocket 实时会话（/ws/{session_id}）。
  • 会话与消息查询（/sessions、/sessions/{id}/messages）。
  • Turn 级历史观测（/sessions/{id}/turns、/sessions/{id}/turns/{turn_id}/context）。
  • Turn 级 RAG 检索调试（POST /sessions/{id}/turns/{turn_id}/rag-debug）。
  • 模型清单与默认配置（/models）。
  • Agent 管理（/agents CRUD）。
  • 知识源管理（/knowledge-sources CRUD）。
  • Agent 知识挂载（/agents/{agent_id}/mounts）。
  • 文档上传、查询与删除（/knowledge-sources/{id}/documents）。
  • 摄取任务触发与查询（/knowledge-sources/{id}/ingest）。

快速导航

数据流说明

  • SSE：客户端 POST 请求后，服务端持续输出 data: {json} 事件。
  • WebSocket：连接后可推送历史消息与新回复。
  • Agent 知识过滤：当请求携带 agent_id 时，RAG 检索会根据 Agent 挂载的知识源进行过滤。
  • Chat 运行时选择：agent_type 只区分 chat/etl/document_extraction；chat Agent 的具体运行时由 orchestrator_key 选择，服务端同时在 /stream 与 evaluation runner 中走同一注册表工厂。
  • Agent 固定响应：仅 chat Agent 支持 message_type_response_config。当请求携带 agent_id 且命中该配置时，POST /stream 会优先按 message_type + message 匹配 message_key_responses[]，未命中时再回退到该 message_type 的默认兜底文案，并保持现有 SSE token / done 格式；WebSocket chat session 会在进入编排前解析 [message_type=<type>]\n<body> content，并用 <body> 参与同一套匹配。fixed response 路径不会调用 orchestrator，也不会写入新的会话模型覆盖配置。
  • 失效 Agent 保护：当 POST /stream 或 WS /ws/{session_id} 消息携带不存在的 agent_id 时，服务会拒绝本次请求；HTTP 路径返回 404，错误载荷包含 code=agent_not_found 与原始 agent_id。
  • 观测持久化：每次用户输入与助手回复会写入 conversation_turns，并写入 turn_context_snapshots 记录上下文快照与 trace 关联信息。
  • Langfuse 桥接：当 LANGFUSE_ENABLED=true 且凭据可用时，服务会把同一个内部 trace_id 导出到 Langfuse，并在 turn 上下文响应中暴露可选的 langfuse_trace_url。
  • Conversations 历史导出：Admin Conversations 页面会组合 /sessions/{id}/turns 与 /sessions/{id}/turns/{turn_id}/context，导出兼容评测 CSV 的 input/expected/metadata。导出行仍保持 turn 级，但导出候选范围已扩展到单个 Turn、当前 Session、已勾选 Sessions 或当前筛选结果对应的全部 Sessions。
  • Conversations RAG 调试：Admin Conversations 页面可基于选中 Turn 调用 /sessions/{id}/turns/{turn_id}/rag-debug，使用该 Turn 的 effective_input 作为默认 query，返回 active sources、raw vector candidates、final retrieval、keyword fallback 运行信息，以及 expected-chunk 诊断。
  • 历史身份保留：sessions 与 conversation_turns 会保留 Agent ID/名称快照，因此 Agent 删除后，/sessions 与 /sessions/{id}/turns 仍可展示历史 Agent 身份。

延伸阅读

端点与数据模型的详细说明请查看：