ai-demo1：完整的本地AI生产栈复现，从OAuth到可观测性的端到端实践

本文介绍ai-demo1项目——一个本地开发实验室，完整复现生产级AI聊天栈，涵盖OAuth认证、LLM推理代理、MCP工具调用和OpenTelemetry链路追踪，所有服务均在本地运行，解决开发者面临的云端服务可见性缺失与从零搭建复杂度高的两难问题。

在开发AI应用时，开发者常面临选择：云端托管服务快速但缺乏系统可见性，从零搭建则工程复杂度极高。生产环境AI系统涉及认证授权、模型推理代理、工具调用、链路追踪等组件，集成调试需反复部署到远程环境。ai-demo1提供本地解决方案，所有服务在localhost运行（除xAI API key外无外部依赖），让开发者可控环境中理解、调试、扩展各组件。

ai-demo1采用微服务架构，含4核心服务：

1. oauth-idp（端口9000）：自定义OAuth2身份提供商，实现Authorization Code+PKCE流程，RS256签发JWT。
2. chat-back（端口8100）：AI推理代理，提供OpenAI兼容API，路由请求到xAI/Copilot等上游LLM。
3. mcp-gw（端口8200）：MCP工具网关，提供mock工具（如天气查询）测试工具调用流程。
4. chat-front（端口8300）：基于Pydantic AI的聊天Agent，负责OAuth认证、调用chat-back、执行MCP工具调用。 技术选型：Python3.12+uv（极速包管理）、FastAPI+uvicorn（HTTP服务）、Pydantic AI（Agent构建）、MCP协议（工具交互）、OpenTelemetry（链路追踪）。

完整请求生命周期：

1. 用户认证：chat-front发起PKCE流程，获取访问令牌。
2. 聊天请求：用户输入问题，chat-front构造请求发送到chat-back。
3. 模型路由：chat-back按模型前缀转发到对应LLM提供商。
4. 工具调用决策：LLM判断是否调用工具（如天气查询），输出tool_call请求指定调用get_weather工具，并提供参数{"location": "北京"}。
5. 工具执行：chat-front通过MCP与mcp-gw交互，获取结果如{"temperature":22, "condition":"sunny"}。
6. 最终回复：chat-front将工具结果追加到对话，LLM生成自然语言回复。
7. 链路追踪：各环节生成OTel数据，可视化于Grafana Tempo。 本地开发工作流：通过launch.sh启动/停止服务、查看状态/日志。 测试体系：单元测试（pytest）覆盖各服务；集成测试（21场景）验证端到端流程（OAuth、推理、工具调用等）。

ai-demo1的价值：

• 生产预演：提供生产等价本地环境，验证架构、测试故障、优化性能、实验技术选型。
• 教育意义：展示AI系统组件分解、交互协议、Python异步最佳实践、可观测性实现。
• 扩展基础：模块化设计支持添加新工具、LLM提供商、认证方案或前端界面。

当前局限：

• 持久化存储缺失：用户数据/会话状态存于内存，重启丢失。
• 水平扩展不足：单进程运行，未考虑多实例部署。
• 安全配置待优化：自签名证书、硬编码密钥需替换为生产级方案。
• 监控告警缺失：仅有链路追踪，缺少指标收集与告警机制。 未来方向：解决上述生产化gap，助力开发者从demo走向生产。

ai-demo1代表"本地优先"AI开发范式：在云端部署前，先在可控本地环境构建、测试、理解系统。此范式在AI工程复杂度增长的今天尤为重要，让开发者成为系统主人而非黑盒服务束缚。推荐希望深入AI系统架构或规划AI基础设施的开发者研究该参考实现。