Docubrain Agent

DocuBrain代理🧠

项目简介

DocuBrain代理 集成了内部文档搜索（RAG）和外部工具执行的自主式AI代理系统。

对于用户的自然语言的提问AI自动确定“是否需要搜索”“是否需要计算”，并使用适当的工具进行回答。不仅仅是聊天室代理工作流中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

______________________________________________________________________

示威

🚀 现场演示: https://docubrain-prod-ae29a.web.app/

请尝试实际运行的应用程序！ChatGPT在轻松的界面上AI您可以体验代理的自主工具选择和基于依据的回答生成。

______________________________________________________________________

主要特征

🤖 自主代理

AI根据情况选择并执行最佳工具。用户只需传达“想知道什么”而不是“使用什么”就可以了。

📚 RAG（检索增强生成）

PDF对文档进行矢量检索，生成有根据的回答。防止产生幻觉，提供可靠的信息。

🔧 多工具集成

自主区分知识检索、计算工具等多个功能。易于扩展的体系结构。

🏗️ MCP（模型上下文协议）

Anthropic啊OpenAI也采用行业标准协议。工具和AI中所述修改相应参数的值。

💬 Intuitive UI/UX (直观界面）

类似ChatGPT的接口 具有高级功能：

• 多会话管理：在侧边栏集中管理多个聊天记录
• 永続化: localStorage 的重载耐性（对话不会消失）
• 反射式设计：完全支持移动/平板/台式机
• UX细节: Loading状态可视化IME对应，源引用容易看的表示

☁️ 全克劳德

Firebase Hosting + Cloud Run实现可扩展的基础设施。无服务器配置使运营成本最小化。

______________________________________________________________________

系统体系结构

graph TB
    subgraph "Frontend - Firebase Hosting"
        A[React + TypeScript
Vite + Tailwind CSS]
    end
    
    subgraph "Backend - Google Cloud Run"
        B[FastAPI
Python 3.11]
        C[MCP Server
stdio communication]
        D[Agent Runner
Gemini API]
    end
    
    subgraph "External Services"
        E[Qdrant Cloud
Vector Database]
        F[Google Gemini API
gemini-2.5-flash]
    end
    
    A -->|HTTPS/JSON| B
    B -->|subprocess| C
    D -->|Function Calling| C
    C -->|retrieve_knowledge| E
    C -->|add/multiply| C
    D -->|LLM Request| F
    
    style A fill:#61DAFB,stroke:#333,stroke-width:2px,color:#000
    style B fill:#009688,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#FF6B6B,stroke:#333,stroke-width:2px,color:#fff
    style D fill:#4ECDC4,stroke:#333,stroke-width:2px,color:#000
    style E fill:#7C4DFF,stroke:#333,stroke-width:2px,color:#fff
    style F fill:#8E75B2,stroke:#333,stroke-width:2px,color:#fff

数据流

1. 前端：用户聊天UI在中输入问题
2. 快速API: /api/chat 在端点接收请求
3. Agent Runner: Gemini API的Function Calling提交请求
4. MCP服务器: AI选择的工具（retrieve_knowledge, add, multiply），模板名称将采用不同的格式
5. Qdrant: RAG框中，选择“默认值”
6. 回应: AI生成最终回答并返回前端

______________________________________________________________________

使用技术

前端

后端

人工智能与数据

开发运维

______________________________________________________________________

机能一覧

1.RAG（检索增强生成）

• PDF文档上载分析
• 文本组块和矢量嵌入
• Qdrant语义搜索
• 以检索结果为依据的回答生成
• 显示源引用（显示从哪个文档获取的信息）

2.自主代理

• 自主工具选择: AI分析用户的意图，确定所需的工具
• 函数调用: Gemini API利用本地功能
• 多步推理：执行多个工具组合的复杂任务

3.提供工具

*（未来可扩展：API调用、数据库查询、外部服务协作等）*

4.现代聊天UI

• ChatGPT简单的接口：在侧边栏中管理多个对话
• 会话持久化: localStorage耐重载性
• 实时反馈: Loading状态可视化，自动滚动
• 源引用可视化：从哪个文档获取信息一目了然
• 反射式设计：完全支持移动/平板/台式机
• IME対応：日本语入力中の误送信防止

______________________________________________________________________

开发的讲究（Technical Challenges）

在本项目中，我们致力于实际业务级别的技术挑战，而不是单纯的教程实施。

🚀 1. MCP (Model Context Protocol) 实施

课题: AI工具协作标准化和松散耦合

传统Function Calling在实现中，工具定义和后端逻辑往往是紧密耦合的。在本项目中MCP（模型上下文协议） 采用AI实现了将和工具松散耦合的设计。

技术实施点

1. Docker在动态输入提示中MCP服务器启动

Cloud Run在环境中MCP将服务器启动为子进程，然后单击stdio进行了通过通信合作的安装。

# backend/app/services/mcp_client.py
async def start_mcp_server():
    """MCPサーバーをサブプロセスとして起動（stdio通信）"""
    server_params = StdioServerParameters(
        command="python",
        args=["/app/app/mcp/server.py"],  # 絶対パス指定が重要
        env=None
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            return session

2.解决绝对路径

最初，通过指定相对路径Cloud Run 出现上面找不到模块的错误。Docker容器中的绝对路径（/app/app/mcp/server.py），模板名称将采用不同的格式。

3.贯彻异步处理

FastAPI的异步处理程序MCP正确集成客户端异步通信。

async def run_agent(user_message: str) -> str:
    """エージェントを実行し、MCPツールを呼び出す"""
    async with get_mcp_session() as session:
        # ツールリストを取得
        tools_list = await session.list_tools()
        
        # Gemini APIにFunction Callingリクエスト
        response = model.generate_content(...)
        
        # AIが選択したツールをMCP経由で実行
        tool_result = await session.call_tool(tool_name, arguments=args)

为什么MCP选择了吗

• 扩张性：易于添加新工具（仅通过MCP服务器端的更改完成）
• 保守性：工具逻辑和AI逻辑分离
• 标准化: Anthropic啊OpenAI也采用的行业标准协议

______________________________________________________________________

🤖 2.构建自主代理

课题: AI动态工具选择和运行

它实现了一个代理，可以根据用户的意图自主选择和运行适当的工具，而不是单纯的聊天室。

実装戦略

1. Function Calling利用率

Gemini API的，之Function Calling使用功能AI让我判断了“使用哪个工具”。

tools = [
    {
        "name": "retrieve_knowledge",
        "description": "社内ドキュメントから関連情報を検索します",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "検索クエリ"}
            }
        }
    },
    # ... 他のツール定義
]

model = genai.GenerativeModel(
    model_name="gemini-2.5-flash",
    tools=tools
)

2.多回合对话

AI实施多回合对话，接收执行工具的结果，再次进行推理。

User: "売上レポート2024のQ3実績は？"
  ↓
AI: retrieve_knowledge("売上レポート2024 Q3") を呼び出し
  ↓
Tool: [検索結果] "Q3実績: 1200万円"
  ↓
AI: "2024年Q3の売上実績は1200万円です。"

下功夫的要点

• 提高意图分类的精度：通过提示工程提高适当的工具选择率
• 错误处理：工具执行失败时的回退处理
• 上下文管理：保持对话历史记录，应对连续提问

______________________________________________________________________

🔒 3. CORS和安全

课题: Cloud Run (Backend) 和Firebase Hosting (Frontend) 之间的安全通信

解决策

1. CORS配置中间件

# backend/app/main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://docubrain-agent.web.app",
        "http://localhost:5173"  # 開発環境
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

2.根据环境变量API密钥管理

# Cloud Run デプロイ時
gcloud run deploy docubrain-backend \
  --set-env-vars GEMINI_API_KEY=secret:gemini-key \
  --set-env-vars QDRANT_API_KEY=secret:qdrant-key

3.型安全通信

前端和后端TypeScript/Pydantic的架构，防止运行时出错。

______________________________________________________________________

� 4.前端状态管理UX设计

课题：可以作为实用的应用程序使用UI/UX实现

不仅仅是聊天室，以“每天都想使用”的应用程序为目标，进行了以下设计。

安装的办法

1.客户端会话管理

useState 和 useEffect 组合多个聊天记录React的状态进行管理。

const [sessions, setSessions] = useState([]);
const [currentSessionId, setCurrentSessionId] = useState(null);

// セッション作成
const createNewSession = () => {
  const newSession: ChatSession = {
    id: Date.now().toString(),
    title: '新しいチャット',
    messages: [{ role: 'assistant', content: 'こんにちは！...' }],
    createdAt: Date.now(),
  };
  setSessions(prev => [newSession, ...prev]);
  setCurrentSessionId(newSession.id);
};

2. LocalStorage持久化

在保护隐私的同时保留历史记录，不影响后端。

// 保存
useEffect(() => {
  if (sessions.length > 0) {
    localStorage.setItem('docubrain_sessions', JSON.stringify(sessions));
  }
}, [sessions]);

// 読み込み
useEffect(() => {
  const saved = localStorage.getItem('docubrain_sessions');
  if (saved) {
    const parsedSessions: ChatSession[] = JSON.parse(saved);
    setSessions(parsedSessions);
  }
}, []);

3. UX对细节的讲究

为什么要做这个设计

• 无状态后端: Cloud Run对于每个请求，容器都会启动和停止。如果在服务器侧进行会话管理Redis等需要外部存储的复杂性。
• MVP设计：首先在客户端完成，在用户增加的阶段Firestore过渡到协作的阶段性设计。
• 隐私：不向服务器发送对话履历，通过在浏览器内完结来保护数据主权。

______________________________________________________________________

��️ 5.全栈实现

课题：从前端到基础设施的一致设计和构建

成果

• 设计：系统架构、数据流设计
• 前端: React + TypeScript 中的UI实施、状态管理、UX设计
• 后端: FastAPI 中的异步API实现
• AI统合: Gemini API、Qdrant集成RAG管线构造
• 基础设施: Docker容器化Cloud Build根据CI/CD、Cloud Run部署到
• 调试: Cloud Run分析日志、确定和修复路径解决问题

全部都是一个人完成的，证明了实务水平的全栈开发能力。

______________________________________________________________________

安装过程

前提条件

• Node.js 18+
• Python 3.11+
• Docker&Docker编写
• Google Cloud 帐户（启用Gemini API）
• Qdrant Cloud 账户

1.克隆存储库

git clone https://github.com/yourusername/docubrain-agent.git
cd docubrain-agent

2.设置环境变量

后端

# backend/.env
GEMINI_API_KEY=your_gemini_api_key
QDRANT_URL=https://your-cluster.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key
QDRANT_COLLECTION_NAME=docubrain_knowledge

前端

# frontend/.env
VITE_API_BASE_URL=http://localhost:8000

3.启动本地开发环境

后端

docker-compose up --build

后端 http://localhost:8000 中所述修改相应参数的值。

前端

cd frontend
npm install
npm run dev

前端 http://localhost:5173 中所述修改相应参数的值。

4.动作确认

1. 在浏览器中 http://localhost:5173 访问
2. 在聊天屏幕上输入问题（例如：“销售报告”）
3. AI选择“工具”，并确认是否显示答案

______________________________________________________________________

项目配置

docubrain-agent/
├── frontend/                 # React + TypeScript
│   ├── src/
│   │   ├── components/      # UIコンポーネント
│   │   ├── api.ts          # バックエンド通信
│   │   ├── types.ts        # 型定義
│   │   └── App.tsx
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                 # FastAPI + Python
│   ├── app/
│   │   ├── api/            # APIエンドポイント
│   │   │   └── agent.py
│   │   ├── services/       # ビジネスロジック
│   │   │   ├── agent_runner.py
│   │   │   ├── mcp_client.py
│   │   │   └── search.py
│   │   ├── mcp/           # MCPサーバー
│   │   │   └── server.py
│   │   ├── schemas/       # Pydanticスキーマ
│   │   └── main.py
│   ├── Dockerfile
│   └── pyproject.toml
│
├── docker-compose.yml
└── README.md

______________________________________________________________________

部署

Cloud Run 部署到

# Cloud Buildでビルド
gcloud builds submit --config cloudbuild.yaml

# Cloud Runにデプロイ
gcloud run deploy docubrain-backend \
  --image gcr.io/your-project-id/docubrain-backend \
  --platform managed \
  --region asia-northeast1 \
  --allow-unauthenticated \
  --set-env-vars GEMINI_API_KEY=secret:gemini-key

Firebase Hosting 部署到

cd frontend
npm run build
firebase deploy --only hosting

______________________________________________________________________

今后的展望

机能扩张

• \[ \] 认证机能: Firebase Authentication用户管理
• \[ \] 会话历史记录持久化: Firestore连携
• \[ \] 多用户支持：按用户分离知识库
• \[ \] 扩充工具:

- 外部API呼叫（天气、新闻等） - 执行数据库查询 - 文件操作（PDF生成、Excel输出等）

技术改善

• \[ \] 流响应：实时回答生成
• \[ \] 高速缓存：高速缓存搜索结果
• \[ \] 监视：云记录/监控統合
• \[ \] 测试：单体测试E2E扩充测试

UI/UX

• \[ \] 支持标记：显示回答的丰富文本
• \[ \] 音声入力：语音转文本統合
• \[ \] 多言语对应: i18n実装

______________________________________________________________________

许可证

MIT许可证

______________________________________________________________________

开発者

尤塔 Yokkaichi

这个项目是现代的全堆栈开发AI它是为了证明整合、云基础设施建设的技能而创建的。

技术问题和反馈GitHub的，之Issue求值时使用曲面法线的原始方向。

______________________________________________________________________

内置于❤️ 尖端技术