4.1 · 聊天架构与数据模型（Chat Architecture and Data Models）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节4.1 状态全文译文模块智能体运行时、检索、召回与索引、模型调用与提供方适配、文档对象与元数据

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Chat Architecture and Data Models 上一章4 下一章4.2

源码线索

backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
backend/onyx/auth/schemas.py
backend/onyx/auth/users.py
backend/onyx/chat/chat_state.py
backend/onyx/chat/chat_utils.py
backend/onyx/chat/llm_loop.py
backend/onyx/chat/llm_step.py
backend/onyx/chat/models.py
backend/onyx/chat/process_message.py
backend/onyx/chat/prompt_utils.py

模块标签

智能体运行时
检索、召回与索引
模型调用与提供方适配
文档对象与元数据
系统架构

章节正文

聊天架构与数据模型

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/4.1-chat-architecture-and-data-models

聊天架构与数据模型

相关源文件

本章引用的主要源码文件：

backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.py
backend/onyx/auth/schemas.py
backend/onyx/auth/users.py
backend/onyx/chat/chat_state.py
backend/onyx/chat/chat_utils.py
backend/onyx/chat/llm_loop.py
backend/onyx/chat/llm_step.py
backend/onyx/chat/models.py
backend/onyx/chat/process_message.py
backend/onyx/chat/prompt_utils.py
backend/onyx/context/search/models.py
backend/onyx/context/search/pipeline.py
backend/onyx/db/chat.py
backend/onyx/db/enums.py
backend/onyx/db/models.py
backend/onyx/db/user_preferences.py
backend/onyx/deep_research/dr_loop.py
backend/onyx/prompts/chat_prompts.py
backend/onyx/prompts/deep_research/__init__.py
backend/onyx/prompts/deep_research/dr_tool_prompts.py
backend/onyx/prompts/deep_research/orchestration_layer.py
backend/onyx/prompts/deep_research/research_agent.py
backend/onyx/prompts/prompt_utils.py
backend/onyx/prompts/tool_prompts.py
backend/onyx/server/manage/get_state.py
backend/onyx/server/manage/models.py
backend/onyx/server/manage/users.py
backend/onyx/server/query_and_chat/chat_backend.py
backend/onyx/server/query_and_chat/models.py
backend/onyx/tools/fake_tools/research_agent.py
backend/onyx/tools/models.py
backend/onyx/tools/tool_implementations/search/search_tool.py
backend/onyx/tools/tool_runner.py
backend/tests/api/test_api.py
backend/tests/unit/onyx/auth/test_single_tenant_jwt_strategy.py
backend/tests/unit/onyx/chat/test_llm_loop.py
backend/tests/unit/onyx/chat/test_llm_step.py
deployment/aws_ecs_fargate/cloudformation/services/onyx_nginx_service_template.yaml
deployment/aws_ecs_fargate/cloudformation/services/onyx_web_server_service_template.yaml
web/src/hooks/useTokenRefresh.test.tsx
web/src/hooks/useTokenRefresh.ts
web/src/providers/UserProvider.tsx

目的与范围

本文档记录了支撑 Onyx 聊天系统的数据模型和架构模式。内容涵盖持久化存储模式、支持分支功能的基于树的消息结构，以及在大语言模型（LLM）编排循环中使用的中间处理模型。

数据库模型：ChatSession、ChatMessage、ToolCall 和 SearchDoc 的持久化模式。
消息树结构：通过父子关系实现对话分支和回复重新生成。
处理模型：消息生成过程中使用的数据结构（ChatMessageSimple、LlmStepResult、AnswerStream）。
状态管理：用于在多周期大语言模型（LLM）执行期间累积状态的 ChatStateContainer。
流式架构：类型化的 Packet 对象如何从 FastAPI 后端流向前端。

核心数据库模型

聊天系统使用几个主要的 SQLAlchemy 模型来持久化存储对话及其关联的元数据。

ChatSession 模型

ChatSession 代表一个唯一的对话线程。它是所有消息的容器，并定义了交互的配置（角色、用户、项目）。

关键字段：

字段	类型	描述
`id`	UUID	主键，唯一的会话标识符。
`user_id`	UUID	指向 `User` 表的外键（匿名用户可为空）。
`persona_id`	int	指向 `Persona`（AI 助手配置）的外键。
`description`	str	面向用户的会话标题，通常自动生成。
`current_alternate_model`	str	专门为此会话设置的模型覆盖。
`shared_status`	枚举	链接分享的 `PUBLIC` 或 `PRIVATE` 状态。
`onyxbot_flow`	bool	指示会话是否源自 Slack/OnyxBot。
`project_id`	int	与特定项目上下文的可选关联。

来源：backend/onyx/db/models.py:1380-1440

ChatMessage 模型

ChatMessage 代表会话中的单个轮次。消息形成一个树状结构，以支持分支和重新生成功能。

关键字段：

字段	类型	描述
`id`	int	主键，自增。
`chat_session_id`	UUID	指向 `ChatSession` 的外键。
`parent_message`	int	分支中前一条消息的 ID。
`latest_child_message`	int	指向分支中当前活跃子消息的指针，用于导航。
`message_type`	枚举	`USER`、`ASSISTANT` 或 `SYSTEM`。
`message`	str	消息的实际文本内容。
`token_count`	int	用于上下文窗口管理的 Token 计数。
`citations`	JSONB	将引用索引映射到 `SearchDoc` ID。
`files`	JSONB	`FileDescriptor` 对象列表（图片、文档等）。

来源：backend/onyx/db/models.py:1443-1570

ToolCall 模型

存储大语言模型（LLM）在特定助手轮次中请求的工具调用的详细信息。

关键字段：

字段	类型	描述
`id`	int	主键。
`message_id`	int	指向触发调用的 `ChatMessage` 的外键。
`tool_name`	str	工具名称（例如 `SearchTool`、`PythonTool`）。
`tool_args`	JSONB	大语言模型（LLM）生成的参数。
`tool_result`	JSONB	工具执行后的输出/结果。