Neural Foundry

NeuralFoundry

概述

1.多用户支持

• 每个用户都有一个唯一的ID和个人资料。
• 用户可以创建、查看和管理多个聊天会话。

2.聊天会话

• 每个用户都可以创建多个聊天会话。
• 每个聊天会话都存储元数据(title, created_at)并且与它的创建者相关联。

3.消息记忆和上下文

• 聊天消息（用户+助手）存储在数据库中。
• 每条消息都转换为 矢量嵌入 使用OpenAI嵌入(text-embedding-3-small，1536变暗）。

4.情境响应生成

• 当用户发送查询时，系统：

1. 检索 顶部相似的过去消息 通过向量相似性搜索从该聊天会话中提取。 1. 将检索到的对话片段作为上下文传递给LLM。 1. 根据上下文生成助手响应，保持聊天的连续性。

5.路由器和API

• 用户路由器： 创建用户、获取用户信息、列出用户聊天记录。
• 聊天路由器： 创建聊天记录（用户链接或通用）、发送消息、获取消息、删除聊天记录、列出所有聊天记录。
• 清晰的RESTful层次结构：

- /users/{user_id}/chats → 用户特定聊天 - /chats/{chat_id} → 聊天特定操作

6.数据库和存储

• PostgreSQL被用作主数据库。
• 使用存储的向量嵌入 pgvector.
• ChatSession ↔ User 关系落实。
• ChatMessage ↔ ChatSession 关系落实。

______________________________________________________________________

为什么这个项目很重要（面向初级人工智能工程师）

NeuralFoundry是一个实践性的模块化RAG游乐场，展示了如何构建真正的AI系统。代码经过精心组织，因此您可以在不重写整个堆栈的情况下研究或交换组件。

使用的技术

• 聊天记忆\

我们将每条消息（用户+助手）存储为文本+向量嵌入。检索提取最近的消息和语义相似的旧消息以保持上下文。

• 知识库（KB）\

每个KB都有存储元数据的文档。我们嵌入块并在查询时检索最相关的块。

• 聊天附件\

您可以将文件直接附加到聊天中。这些文件被处理成块并存储为嵌入，然后仅用作该聊天的额外上下文。

• 分块策略

- PDF、docx、图像、HTML等使用 多语文档 用于结构感知组块。 - .txt 和 .md 直接用重叠分割（简单、快速、可靠）。

• 检索和相似性阈值\

矢量相似性搜索使用 pgvector.\ 相似性阈值（例如，KB块阈值）为 可在设置中配置，因此您可以在不更改代码的情况下调整相关性与召回率。

值得学习的架构模式

• 模块化管道 （聊天管道、KB摄取、附件摄取）\

易于插入其他检索策略：BM25、混合搜索、重新排序等。

• 配置驱动行为\

模型选择、嵌入维度、块大小和阈值可以集中调整。

• 元数据丰富的存储\

我们存储聊天记录、KB和附件的元数据，这使得以后可以进行分析和仪表板。

工装堆栈

• 快速API 用于后端API
• OpenAI Python 软件开发工具包 用于聊天+嵌入
• PostgreSQL+pgvector 用于矢量搜索
• Docker Compose 对于单命令本地开发
• React+Vite 对于前端
• Bash/Docker工具 用于可重复设置

______________________________________________________________________

下一步可以构建的想法

• 更多检索方法\

添加BM25、混合搜索、重新排序或查询扩展。

• 多模型响应\

从不同模型（或不同提示）生成响应A/响应B并进行比较。

• 用户反馈循环\

收集点赞/点赞，并将其输入评估或重新排名。

• 分析和仪表板\

使用存储的元数据显示最常用的KB、附件使用情况、查询模式等。

• 代理/MCP\

使用代理框架添加工具、结构化工作流或多步推理。

______________________________________________________________________

快速入门（Docker Compose）

这是运行所有内容的推荐方式：Postgres+pgvector、后端、前端和pgAdmin。

1.设置环境变量

创建或编辑 /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/.env:

POSTGRES_USER=neuralfoundry
POSTGRES_PASSWORD=neuralfoundry_pw
POSTGRES_DB=neuralfoundry
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

在macOS环境中设置OpenAI密钥（不在 .env):

export OPENAI_API_KEY="your_key_here"

2.运行一切

docker compose -p neuralfoundry-ui -f /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/docker-compose.yml up --build

2.1.重新开始（清除所有数据）

这将删除所有Postgres数据并开始清理。

docker compose -p neuralfoundry-ui -f /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/docker-compose.yml down -v
docker compose -p neuralfoundry-ui -f /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/docker-compose.yml up --build

______________________________________________________________________

您将在日志中看到什么（示例）

后端打印一个紧凑的检索摘要，以便您快速了解模型使用的上下文：

============================================================
🐛 RETRIEVAL RESULTS:
   - Recent messages: 5
   - Older messages: 0
   - KB chunks: 0
   - Attachment chunks: 0
   ⚠️  NO KB RESULTS FOUND!
   ⚠️  No KBs are attached to this chat!
   ℹ️  No attachments found in this chat
============================================================

______________________________________________________________________

数据模型（快速快照）

以下是数据连接方式的基本视图：

User
  └── ChatSession
        ├── ChatMessage (vector embedding)
        ├── ChatAttachment
        │     └── ChatAttachmentChunk (vector embedding)
        └── ChatSessionKB (links chat ↔ KB)

KnowledgeBase
  └── KBDocument
        └── KBChunk (vector embedding)

3.开放式服务

• 后端：http://localhost:8000
• 前端：http://localhost:5173
• pgAdmin：http://localhost:8081

3.1 Docker与YAML实现的分离

为了避免碰撞 NeuralFoundry-yaml，此UI堆栈使用单独的默认值：

• Postgres主机端口： 5433
• pgAdmin主机端口： 8081

如果需要，您可以覆盖这些：

NF_UI_DB_PORT=5433 NF_UI_PGADMIN_PORT=8081 docker compose -p neuralfoundry-ui -f /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/docker-compose.yml up --build

4.pgAdmin连接（编写）

pgAdmin将自动注册一个名为的服务器 neuralfoundry. 如果系统提示输入密码，请使用：

• 密码： neuralfoundry_pw

______________________________________________________________________

手动Docker（仅限Postgres+pgAdmin）

如果你想在本地运行后端/前端：

PostgreSQL与pgvector

docker run --name nf-postgres \
  -e POSTGRES_USER=neuralfoundry \
  -e POSTGRES_PASSWORD=neuralfoundry_pw \
  -e POSTGRES_DB=neuralfoundry \
  -p 5432:5432 \
  -d pgvector/pgvector:pg16

pgAdmin

docker run --name nf-pgadmin \
  -e PGADMIN_DEFAULT_EMAIL=thomaskuttyreji.1396@gmail.com \
  -e PGADMIN_DEFAULT_PASSWORD=admin_pw \
  -p 8080:80 \
  -d dpage/pgadmin4

pgAdmin连接（手动）

• 主机名： host.docker.internal
• 端口： 5432
• 用户名： neuralfoundry
• 密码： neuralfoundry_pw
• 数据库： neuralfoundry

______________________________________________________________________

本地开发（无Docker Compose）

cd /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload

前端：

cd /Users/thomaskuttyreji/Documents/GitHub/NeuralFoundry/frontend
npm install
npm run dev