# ai-demo1：完整的本地AI生产栈复现，从OAuth到可观测性的端到端实践 > 一个本地开发实验室项目，完整复现生产级AI聊天栈：OAuth认证、LLM推理代理、MCP工具调用和OpenTelemetry链路追踪，全部在本地运行。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-04-05T05:43:41.000Z - 最近活动: 2026-04-05T05:50:25.808Z - 热度: 152.9 - 关键词: Pydantic AI, OAuth, AI Gateway, MCP, OpenTelemetry, 微服务, LLM推理, 本地开发, 可观测性 - 页面链接: https://www.zingnex.cn/forum/thread/ai-demo1-ai-oauth - Canonical: https://www.zingnex.cn/forum/thread/ai-demo1-ai-oauth - Markdown 来源: ingested_event --- ## 引言：为什么需要本地AI生产栈\n\n在开发AI应用时，开发者常常面临一个两难选择：要么使用云端托管服务快速上手但失去对系统的可见性，要么从零搭建但工程复杂度极高。生产环境中的AI系统涉及多个关键组件——认证授权、模型推理代理、工具调用、链路追踪——这些组件的集成调试往往需要反复部署到远程环境。\n\nai-demo1项目提供了一个优雅的解决方案：它是一个本地开发实验室，完整复现了生产级AI聊天栈的每个环节。所有服务都在localhost运行，无需外部依赖（除xAI API key外），让开发者能够在完全可控的环境中理解、调试和扩展每个组件。\n\n## 架构概览：四个核心服务\n\nai-demo1采用微服务架构，将AI系统的不同职责拆分为四个独立服务：\n\n### 1. oauth-idp（端口9000）\n\n自定义OAuth2身份提供商，实现Authorization Code + PKCE流程，使用RS256算法签发JWT。这是整个系统的安全入口，负责用户认证和令牌管理。\n\n### 2. chat-back（端口8100）\n\nAI推理代理服务，提供OpenAI兼容的API接口。它负责将请求路由到不同的上游LLM提供商（xAI或Copilot），是模型调用的统一入口。\n\n### 3. mcp-gw（端口8200）\n\nMCP（Model Context Protocol）工具网关，提供mock工具实现（如获取经纬度、查询天气）。这让AI Agent能够在不依赖外部API的情况下测试工具调用流程。\n\n### 4. chat-front（端口8300）\n\n基于Pydantic AI的聊天Agent，是用户直接交互的入口。它负责OAuth认证、调用chat-back进行推理、执行MCP工具调用，并将结果反馈给LLM。\n\n## 数据流：一次完整请求的生命周期\n\n理解ai-demo1的最佳方式是跟踪一次完整的用户请求如何流经整个系统：\n\n### 第一步：用户认证（PKCE流程）\n\n用户通过chat-front发起登录请求。chat-front作为OAuth客户端，向oauth-idp发起PKCE（Proof Key for Code Exchange）授权流程。这是一种安全的OAuth模式，特别适用于单页应用和移动应用。\n\n用户完成认证后，oauth-idp返回访问令牌（Access Token），chat-front将其存储用于后续请求。\n\n### 第二步：发起聊天请求\n\n用户在chat-front输入问题，例如"今天北京的天气怎么样？"。chat-front构造OpenAI兼容的请求格式，发送到chat-back的`/v1/chat/completions`端点。\n\n请求中包含：\n- 认证头（Bearer Token）\n- 模型名称（如`xai:grok-4-1-fast-reasoning`）\n- 消息历史\n- 可用工具列表（通过MCP发现）\n\n### 第三步：模型路由与推理\n\nchat-back根据模型名称前缀决定路由：\n- `xai:`前缀 → 转发到xAI API\n- `copilot:`前缀 → 转发到GitHub Copilot Chat API\n\n这种设计让开发者可以在同一接口下对比不同提供商的模型表现。\n\n### 第四步：工具调用决策\n\nLLM分析用户问题，判断是否需要调用工具。对于天气查询，模型会输出一个`tool_call`请求，指定调用`get_weather`工具，并提供参数`{"location": "北京"}`。\n\n### 第五步：工具执行\n\nchat-front收到包含`tool_call`的响应后，负责实际执行工具调用。它通过MCP over HTTP协议与mcp-gw通信，传入工具名称和参数。\n\nmcp-gw返回工具执行结果，如`{"temperature": 22, "condition": "sunny"}`。\n\n### 第六步：结果反馈与最终回复\n\nchat-front将工具执行结果作为新消息追加到对话历史，再次发送给chat-back。LLM基于工具返回的数据生成自然语言回复："北京今天天气晴朗，气温22度。"\n\n### 第七步：链路追踪\n\n整个过程的每个环节都通过OpenTelemetry生成追踪数据，包括：\n- 请求在各个服务间的流转\n- 每个操作的耗时\n- 错误和异常信息\n\n这些数据被发送到Grafana Tempo，开发者可以在Grafana中可视化查看完整的请求链路。\n\n## 技术选型与工程实践\n\n### Python 3.12 + uv\n\n项目采用Python 3.12作为基础运行时，使用uv作为包管理器。uv是Astral公司开发的极速Python包管理工具，相比pip具有数量级的速度提升，特别适合需要频繁安装依赖的开发环境。\n\n### FastAPI + uvicorn\n\n除mcp-gw外，所有HTTP服务都基于FastAPI框架构建。FastAPI提供：\n- 自动生成的OpenAPI文档\n- 基于Pydantic的请求/响应校验\n- 原生异步支持\n- 类型提示友好的开发体验\n\n### Pydantic AI\n\nchat-front使用Pydantic AI框架构建Agent。这是Pydantic团队推出的AI应用开发框架，特点包括：\n- 结构化输出验证\n- 类型安全的工具定义\n- 内置的Agent循环管理\n- 与Pydantic生态的无缝集成\n\n### MCP（Model Context Protocol）\n\nMCP是Anthropic提出的开放协议，用于标准化AI模型与外部工具的交互。ai-demo1使用FastMCP实现MCP服务器，并通过Streamable HTTP传输层与客户端通信。\n\n### OpenTelemetry\n\n可观测性是现代分布式系统的关键。ai-demo1在chat-back和mcp-gw中集成了OTel SDK，使用GenAI语义约定标记LLM相关操作，并通过W3C Traceparent头实现分布式追踪的上下文传递。\n\n## 本地开发工作流\n\n### 启动所有服务\n\n项目提供统一的启动脚本`launch.sh`，按依赖顺序启动所有服务：\n\n```bash\n./launch.sh\n```\n\n启动顺序为：oauth-idp → chat-back → mcp-gw → chat-front。每个服务启动后都会进行健康检查，确保依赖就绪后才启动下游服务。\n\n### 查看服务状态\n\n```bash\n./launch.sh status\n```\n\n显示每个服务的运行状态和进程ID。\n\n### 查看日志\n\n```bash\n# 查看所有服务日志\n./launch.sh logs\n\n# 查看特定服务日志\n./launch.sh logs chat-back\n```\n\n日志文件存储在`.logs/`目录，按服务分类。\n\n### 停止服务\n\n```bash\n./launch.sh stop\n```\n\n优雅地停止所有服务并清理进程文件。\n\n## 测试体系\n\nai-demo1包含完整的测试覆盖，从单元测试到集成测试：\n\n### 单元测试\n\n每个服务都有独立的测试套件，使用pytest运行：\n\n```bash\ncd oauth-idp && uv run pytest tests/ -v\ncd chat-back && uv run pytest tests/ -v\ncd mcp-gw && uv run pytest tests/ -v\ncd chat-front && uv run pytest tests/ -v\n```\n\n### 集成测试\n\n集成测试套件`tests/test_integration.py`使用纯Python标准库编写（无需pip安装），验证完整的端到端流程：\n\n```bash\n# 先启动所有服务\n./launch.sh\n\n# 运行集成测试\npython3 tests/test_integration.py\n```\n\n集成测试覆盖21个场景，包括：\n- OAuth完整PKCE流程\n- 用户创建和信息查询\n- 令牌验证和自省\n- chat-back健康检查和模型列表\n- xAI实时推理\n- MCP工具发现和调用\n- chat-front Agent完整循环\n\n## 工程价值与启示\n\n### 生产环境的预演\n\nai-demo1的最大价值在于它提供了一个"生产等价"的本地环境。开发者可以在这个沙盒中：\n\n- 验证架构设计的可行性\n- 测试故障场景和边界情况\n- 优化性能和资源使用\n- 实验不同的技术选型\n\n所有学习都可以在本地完成，无需担心影响生产环境。\n\n### 教育意义\n\n对于希望深入理解AI系统架构的开发者，ai-demo1是一个绝佳的学习资源。它展示了：\n\n- 如何将复杂的AI系统分解为可管理的组件\n- 各组件之间的职责划分和交互协议\n- 现代Python异步服务的最佳实践\n- 可观测性在分布式系统中的实现\n\n### 扩展基础\n\nai-demo1的模块化设计使其易于扩展：\n\n- 添加新的MCP工具只需修改mcp-gw\n- 接入新的LLM提供商只需扩展chat-back的路由逻辑\n- 更换认证方案只需替换oauth-idp\n- 添加新的前端界面只需对接chat-back API\n\n## 局限与未来方向\n\n当前版本的ai-demo1主要面向开发和测试场景，存在一些生产化的gap：\n\n- **持久化存储**：用户数据和会话状态存储在内存中，重启后丢失\n- **水平扩展**：服务以单进程运行，未考虑多实例部署\n- **安全配置**：使用自签名证书和硬编码密钥，需要替换为生产级方案\n- **监控告警**：仅有链路追踪，缺少指标收集和告警机制\n\n这些正是开发者从demo走向生产时需要解决的问题，而ai-demo1提供了清晰的起点。\n\n## 结语：本地优先的AI开发范式\n\nai-demo1代表了一种"本地优先"的AI开发范式：在将代码推送到云端之前，先在完全可控的本地环境中构建、测试和理解整个系统。这种范式在AI工程复杂度日益增长的今天尤为重要——它让开发者真正成为系统的主人，而不是被黑盒托管服务所束缚。\n\n对于任何希望深入理解AI系统架构、或者正在规划自己的AI应用基础设施的开发者，ai-demo1都是一个值得仔细研究的参考实现。