AI Agent基础设施搭建指南：从配置管理到可观测性的完整实践-代码聚汇网

AI Agent基础设施搭建指南：从配置管理到可观测性的完整实践

The Type·2026-09-09·阅读 110 GEO检测（免费）

AI Agent基础设施搭建配置管理

|难度：普通|阅读约 43 分钟

LCODER这个系列走到问数智能体搭建的第二篇，基础设施搭建这块我琢磨了挺久。很多同学聊AI Agent开发，上来就写Agent循环、调Prompt，结果项目跑两步就卡壳——不是模型返回格式不对，就是数据库连不上，要不就是配置写死、到处是硬编码。这篇把我的做法完整过一遍，把问数智能体的地基打牢实。

我先交代一下这个项目的背景：问数智能体，简单说就是用自然语言去查数据，用户问“上个月华东区销售额前五的产品有哪些”，Agent负责理解、拆解、生成SQL、执行查询、再组织成答案。整个链路看着不复杂，但正因为要走通“模型—工具—数据”三层，基础设施层一旦偷懒，后面全要返工。这篇文章适合正在学Agent搭建的、想从纯聊天机器人往业务场景走的人，也适合团队里准备落地问数能力的后端同学，跟着把依赖选型、配置管理、Agent骨架、日志排查这一套跑起来。

这篇会涉及完整的目录设计、关键代码片段、配置方式，以及我在实际搭建中踩过的一些坑。不是哪家的官方教程，是我个人在LCODER项目里沉淀下来的做法，你可以直接拿来用，也可以按自己团队的规范改。

1. 基础设施搭建的整体思路与架构选择

1.1 问数智能体到底需要哪些基础设施

先说个容易被忽视的事实：问数Agent不是一个“大模型API调用”就完事的东西。它本质上是一个系统，由模型调用、Agent调度、工具执行、数据访问、配置管理、日志监控这几层拼起来。

模型调用层：统一封装LLM的请求、超时、重试、参数管理。
Agent调度层：负责任务拆解、工具选择、循环决策，这是“智能”的核心。
工具层：问数场景里最典型的就是数据库查询工具，需要安全地执行SQL并返回结构化结果。
数据访问层：管理数据库连接、连接池、schema缓存。
配置管理：API密钥、模型名、数据库地址、超时等，全部集中管理。
日志与可观测：每轮思考、每次工具调用、每次模型返回都要有迹可循。

很多人一上来就写业务逻辑，最后卡在最基础的问题上：API密钥写死在代码里、换了模型要改十几个文件、数据库连接用一次关一次、Agent一旦循环就卡住超时。这些问题的根源都一样——基础设施层没有做充分的抽象和兜底。

我在LCODER里给自己定了几条原则：模型可以随时换、配置不碰代码、工具可插拔、每步留日志。这四条落实到代码上，就是下面要讲的内容。

1.2 技术选型：框架自研还是用现成的

这两年Agent框架层出不穷，LangChain、LangGraph、AutoGen、CrewAI，还有国内的一些平台级方案。我的选择是：核心不依赖重框架，自己写Agent调度层；工具和模型接入采用轻量封装，按需引入。

为什么这么做，主要三个原因。

第一，问数场景的决策链路相对固定：理解问题、抽取查询条件、生成SQL、执行、总结。用LangChain那套Chain的概念反而绕，自研一个几十行的循环就能跑通，出问题时好排查。

第二，框架的依赖传递太重。很多框架为了兼容各种场景，底层塞了一大堆可选依赖，光装包就能把环境搞乱。而在基础设施搭建这个阶段，依赖越少，越容易定位问题。

第三，从学习和面试的角度来说，自己把Agent循环写一遍，你才真正理解工具注册、上下文组织、终止条件这些东西的运作逻辑。很多“AI Agent面试题”问的就是这些机制的内部设计，框架用多了反而答不上来。

当然不是说框架不好，如果你有团队标准或者是要快速交付，用LangGraph这类工具也完全没问题。我的建议是看你的业务复杂度：链路固定、工具少、追求可控，自研足够；多智能体协作、需要人工介入、复杂状态管理，再上框架。LCODER的定位是实战教学和可控落地，所以我选了前者。

1.3 环境准备与依赖管理

这块我强烈建议别用裸pip + requirements.txt凑合了，试一下uv。uv是目前Python生态里非常顺手的包管理工具，底层用Rust写的，安装依赖的速度比pip快很多，而且自带虚拟环境管理、锁文件机制，一个工具解决大半环境问题。

安装uv只需要一行命令，官方脚本装好后，创建一个Python 3.10+的项目环境：

bash复制uv venv .venv --python 3.10
source .venv/bin/activate  # Windows下是 .venv\Scripts\activate
uv pip install ...

选Python 3.10以上，是因为新版类型语法（X | None、match）、Pydantic v2的特性，以及很多新库对旧版本支持不好。问数项目里我用的Python版本是3.11，稳定且生态兼容最好。

核心依赖我按功能拆分：

bash复制# AI核心
uv pip install openai pydantic pydantic-settings python-dotenv

# 工具与数据访问
uv pip install sqlalchemy pymysql pandas tabulate

# 日志与调试
uv pip install loguru

对照一下每类的作用：openai负责模型调用（目前大多数兼容OpenAI协议的模型都能用），pydantic-settings负责配置管理，sqlalchemy负责数据库连接池和ORM级操作，pandas用来处理查询结果，tabulate把结果格式化成文本给模型总结，loguru专门用来打日志。

这里我要单独说一句：依赖一定要按需要装，不是越多越好。你每多一个第三方库，就多一层版本冲突风险和接口适配成本。比如有些框架自带的查询引擎，最终还是要读写数据库，与其被它的抽象绕晕，不如直接用SQLAlchemy自己掌控。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 配置层与大模型接入

2.1 用pydantic-settings管好所有配置

问数Agent的配置项比普通应用要多：有大模型的API地址、模型名称、温度、超时；有数据库的地址、账号、连接池大小；有Agent的最大迭代次数、日志级别。如果全散在代码里，换环境就是一场灾难。

我用pydantic-settings把所有配置集中到一个地方。它比直接读环境变量好用的地方在于：有类型校验、有默认值、支持嵌套模型、能自动从.env文件和环境变量加载。

python复制# config/settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field

class LLMSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="LLM_")

    api_key: str = Field(..., description="API Key")