Configuración del entorno de agentes de Python

Antes de comenzar a construir un agente de IA, necesitamos preparar un entorno de desarrollo adecuado.

Python es el lenguaje más popular en el campo de la IA y el aprendizaje automático, con un rico ecosistema de bibliotecas y herramientas.

1. Selección de la versión de Python

Para el desarrollo de agentes de IA, recomendamos usarPython 3.9 o superior。

Las siguientes versiones son opciones comunes:

  • Python 3.9: buena estabilidad y mejor compatibilidad
  • Python 3.10: mejoras de rendimiento y nuevas características
  • Python 3.11+: última versión, mejor rendimiento

Nota: algunas bibliotecas pueden tener requisitos específicos de versión de Python; se recomienda consultar la documentación oficial.

2. Instalación de Python

Sistema Windows

  • Visitesitio web oficial de Python
  • Descargue el instalador de la última versión de Python (3.9 o superior)
  • Ejecute el instalador,asegúrese de marcarAdd Python to PATH
  • Una vez completada la instalación, abra el símbolo del sistema (CMD) o PowerShell y escriba:python --version, debería mostrarse el número de versión de Python.

Sistema macOS

macOS generalmente incluye Python preinstalado, pero podría ser una versión antigua. Se recomienda usar Homebrew para instalar:

# 安装 Homebrew(如果尚未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install python@3.9

# 验证安装
python3 --version

Sistema Linux

La mayoría de las distribuciones de Linux ya incluyen Python. Si necesita una versión específica:

# Ubuntu/Debian
sudo apt update
sudo apt install python3.9 python3-pip

# CentOS/RHEL
sudo yum install python39 python39-pip

# 验证安装
python3 --version

3. Configuración del entorno virtual

El uso de entornos virtuales permite aislar las dependencias de diferentes proyectos y evitar conflictos de versiones.

Crear un entorno virtual

# 创建项目目录
mkdir ai-agent-project
cd ai-agent-project

Use uv para crear y activar el entorno virtual. Para más contenido, puede leertutorial de uv。

Instalar uv

pip install uv

Use el comando uv para crear:

# 创建名为 .venv 的虚拟环境(默认)
uv venv

# 激活环境(macOS/Linux)
source .venv/bin/activate

# 激活环境(Windows)
.venv\Scripts\activate

Otras herramientas:

# 使用 venv,Python 3.3+ 内置
python -m venv venv

# 或使用 conda(如果已安装 Anaconda/Miniconda)
conda create -n ai-agent python=3.9
conda activate ai-agent

Activar el entorno virtual

Windows:

venv\Scripts\activate

macOS/Linux:

source venv/bin/activate

Después de la activación, el indicador de la línea de comandos generalmente mostrará el nombre del entorno virtual (como(venv))。

Salir del entorno virtual

deactivate

4. Herramienta de gestión de paquetes pip

pip es la herramienta de gestión de paquetes de Python, utilizada para instalar bibliotecas de terceros.

Comandos comunes:

# 升级 pip 到最新版本
pip install --upgrade pip

# 安装包
pip install package_name

# 安装特定版本
pip install package_name==1.2.3

# 从 requirements.txt 安装所有依赖
pip install -r requirements.txt

# 列出已安装的包
pip list

# 生成 requirements.txt
pip freeze > requirements.txt

5. Estructura de directorios de desarrollo recomendada

Una buena estructura de proyecto ayuda a la gestión y el mantenimiento del código:

ai-agent-project/
├── .env                    # 环境变量文件(不提交到Git)
├── .gitignore             # Git忽略文件
├── requirements.txt       # 项目依赖
├── README.md             # 项目说明
├── src/                  # 源代码目录
│   ├── __init__.py
│   ├── agents/          # Agent相关代码
│   │   ├── __init__.py
│   │   ├── base_agent.py
│   │   └── weather_agent.py
│   ├── tools/           # 工具定义
│   │   ├── __init__.py
│   │   ├── calculator.py
│   │   └── web_search.py
│   ├── memory/          # 记忆系统
│   │   ├── __init__.py
│   │   ├── short_term.py
│   │   └── vector_memory.py
│   └── utils/           # 工具函数
│       ├── __init__.py
│       ├── config.py
│       └── logger.py
├── tests/               # 测试代码
│   ├── __init__.py
│   ├── test_agents.py
│   └── test_tools.py
├── examples/            # 示例代码
│   ├── basic_agent.py
│   └── multi_tool_agent.py
└── notebooks/           # Jupyter笔记本
    └── experiments.ipynb

Instalación de bibliotecas esenciales

El desarrollo de agentes de IA requiere el soporte de una serie de bibliotecas de terceros. A continuación se presentan los métodos de instalación y una breve introducción de las bibliotecas principales.

Instalación de bibliotecas principales

Cree unrequirements.txtarchivo con el siguiente contenido:

# 基础库
python-dotenv>=1.0.0      # 环境变量管理
pydantic>=2.0.0           # 数据验证和设置管理
loguru>=0.7.0             # 日志记录

# AI/ML 相关
openai>=1.0.0             # OpenAI API
anthropic>=0.7.0          # Claude API
google-generativeai>=0.3.0 # Gemini API
sentence-transformers>=2.2.0 # Embedding 模型
chromadb>=0.4.0           # 向量数据库

# Agent 框架
langchain>=0.1.0          # LangChain 框架
langchain-community>=0.0.10 # LangChain 社区工具
langchain-openai>=0.0.5   # LangChain OpenAI 集成
llama-index>=0.10.0       # LlamaIndex(可选)
semantic-kernel>=0.9.0    # Semantic Kernel(可选)

# 工具和工具
requests>=2.31.0          # HTTP 请求
beautifulsoup4>=4.12.0    # HTML 解析
pandas>=2.0.0             # 数据处理
numpy>=1.24.0             # 数值计算

# 开发工具
pytest>=7.4.0             # 测试框架
black>=23.0.0             # 代码格式化
flake8>=6.0.0             # 代码检查
jupyter>=1.0.0            # Jupyter 笔记本

Instale todas las dependencias:

pip install -r requirements.txt

Introducción a las bibliotecas principales

1. LangChain

LangChain es el marco de desarrollo de agentes de IA más popular y proporciona herramientas para construir aplicaciones encadenadas (Chain) y de agentes (Agent).

# LangChain 基本使用示例
from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from langchain.tools import Tool

# 初始化 LLM
llm = ChatOpenAI(temperature=0.7, model="gpt-3.5-turbo")

# 创建工具
tools = [
    Tool(
        name="计算器",
        func=lambda x: str(eval(x)),
        description="用于数学计算"
    )
]

# 创建 Agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 运行 Agent
result = agent.run("计算 25 的平方根")
print(result)

2. LlamaIndex

LlamaIndex (originalmente GPT Index) se centra en la indexación y recuperación de documentos, adecuado para construir sistemas de preguntas y respuestas basados en documentos.

# LlamaIndex 基本使用示例
from llama_index import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms import OpenAI

# 加载文档
documents = SimpleDirectoryReader("./data").load_data()

# 创建索引
index = VectorStoreIndex.from_documents(documents)

# 创建查询引擎
query_engine = index.as_query_engine()

# 查询
response = query_engine.query("文档中提到了哪些AI技术?")
print(response)

3. Semantic Kernel

Semantic Kernel es un marco lanzado por Microsoft que enfatiza la escalabilidad y las aplicaciones de nivel empresarial.

# Semantic Kernel 基本使用示例
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAITextCompletion

# 初始化内核
kernel = sk.Kernel()
api_key = "your-openai-api-key"
kernel.add_text_completion_service(
    "dv",
    OpenAITextCompletion("text-davinci-003", api_key)
)

# 定义技能
skill = kernel.import_semantic_skill_from_directory("./skills", "ExampleSkill")

# 运行技能
context = kernel.create_new_context()
context["input"] = "介绍一下人工智能"
result = skill["Summarize"](context)
print(result)

Verificación de la instalación

Cree un script de verificaciónverify_installation.py:

Ejemplo

# verify_installation.py
import sys

def check_package(package_name, import_name=None):
    """Comprobar si el paquete está instalado"""
    import_name = import_name or package_name
    try:
        __import__(import_name)
        print(f"{package_name} instalado correctamente")
        return True
    except ImportError:
        print(f"{package_name} no está instalado")
        return False

def main():
    print("Comprobando el entorno de desarrollo de agentes de IA...")
    print("=" * 50)

    # Comprobar la versión de Python
    python_version = sys.version_info
    print(f"Versión de Python: {python_version.major}.{python_version.minor}.{python_version.micro}")
    if python_version.major == 3 and python_version.minor >= 9:
        print("La versión de Python cumple los requisitos (>=3.9)")
    else:
        print("La versión de Python no cumple los requisitos; se necesita 3.9 o superior")

    print("\nComprobando bibliotecas principales...")

    # Bibliotecas básicas
    check_package("dotenv", "dotenv")
    check_package("pydantic")
    check_package("loguru")

    # Bibliotecas de IA/ML
    check_package("openai")
    check_package("anthropic")
    check_package("chromadb")
    check_package("sentence_transformers", "sentence_transformers")

    # Marcos de agentes
    check_package("langchain")
    check_package("llama_index", "llama_index")

    # Bibliotecas de herramientas
    check_package("requests")
    check_package("pandas")
    check_package("numpy")

    print("\n" + "=" * 50)
    print("¡Comprobación del entorno completada!")

if __name__ == "__main__":
    main()

Ejecute la verificación:

python verify_installation.py

Solución de problemas comunes de instalación

1. Velocidad de instalación lenta o tiempo de espera agotado

# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用阿里云镜像
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

2. Conflictos de versiones

# 创建新的虚拟环境
python -m venv new_venv
source new_venv/bin/activate  # 或 venv\Scripts\activate

# 重新安装,让 pip 自动解决依赖
pip install --upgrade pip
pip install langchain openai

3. Problemas de plataforma específicos (como Apple Silicon)

# 对于 Apple Silicon (M1/M2/M3),可能需要特定版本
pip install grpcio==1.48.2  # 解决某些兼容性问题

# 或使用 conda
conda install -c conda-forge grpcio

Gestión de claves API

El desarrollo de agentes de IA requiere acceso a varios servicios de API (como OpenAI, Anthropic, DeepSeek, etc.), por lo que es crucial gestionar las claves API de manera segura y eficaz.

1. ¿Por qué se necesita una gestión segura de las claves API?

  • Prevención de fugas: la filtración de claves API puede provocar pérdidas económicas
  • Control de acceso: usar diferentes claves en diferentes entornos
  • Configuración conveniente: unificar el método de configuración en el trabajo en equipo
  • Aislamiento de entornos: usar diferentes claves en los entornos de desarrollo, prueba y producción

2. Gestión de variables de entorno (recomendado)

Use un.envarchivo para gestionar información sensible y no lo envíe al sistema de control de versiones.

Cree un.envarchivo

# API Keys
OPENAI_API_KEY=sk-你的OpenAI密钥
ANTHROPIC_API_KEY=你的Claude密钥
GOOGLE_API_KEY=你的Gemini密钥
SERPAPI_API_KEY=你的搜索API密钥

# 应用配置
APP_ENV=development
LOG_LEVEL=INFO
DEBUG=true

# 数据库配置(如使用)
VECTOR_DB_PATH=./data/vector_db
MAX_MEMORY_ITEMS=1000

Cree un.gitignorearchivo

Asegúrese de que el.envarchivo no se envíe a Git:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/
env.bak/
venv.bak/

# 环境变量
.env
.env.local
.env.*.local

# 数据文件
data/
*.db
*.sqlite
*.sqlite3

# 日志
logs/
*.log

# 编辑器
.vscode/
.idea/
*.swp
*.swo

Use python-dotenv para cargar las variables de entorno

Ejemplo

# config.py
import os
from pathlib import Path
from dotenv import load_dotenv

# Cargar el archivo .env
env_path = Path('.') / '.env'
load_dotenv(dotenv_path=env_path)

class Config:
    """Configuración de la aplicación"""

    # API Keys
    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
    ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
    GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
    SERPAPI_API_KEY = os.getenv("SERPAPI_API_KEY")

    # Configuración de la aplicación
    APP_ENV = os.getenv("APP_ENV", "development")
    LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
    DEBUG = os.getenv("DEBUG", "false").lower() == "true"

    # Configuración de la base de datos
    VECTOR_DB_PATH = os.getenv("VECTOR_DB_PATH", "./data/vector_db")
    MAX_MEMORY_ITEMS = int(os.getenv("MAX_MEMORY_ITEMS", "1000"))

    @classmethod
    def validate(cls):
        """Verificar la configuración necesaria"""
        missing = []

        if not cls.OPENAI_API_KEY:
            missing.append("OPENAI_API_KEY")

        if missing:
            raise ValueError(f"Faltan variables de entorno necesarias: {', '.join(missing)}")

# Ejemplo de uso
config = Config()
print(f"Entorno: {config.APP_ENV}")
print(f"Modo de depuración: {config.DEBUG}")

3. Uso seguro de las claves API

Use variables de entorno en el código

import os
from openai import OpenAI

# 从环境变量读取 API Key
api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    raise ValueError("OPENAI_API_KEY 环境变量未设置")

# 初始化 OpenAI 客户端
client = OpenAI(api_key=api_key)

# 使用客户端
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好"}]
)

Use una clase de configuración

Ejemplo

from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI
from config import Config

class LLMClientFactory:
    """Fábrica de clientes LLM"""

    @staticmethod
    def create_openai_client(model="gpt-3.5-turbo", **kwargs):
        """Crear cliente de OpenAI"""
        Config.validate()  # Verificar la configuración

        return ChatOpenAI(
            model=model,
            openai_api_key=Config.OPENAI_API_KEY,
            temperature=kwargs.get("temperature", 0.7),
            max_tokens=kwargs.get("max_tokens", 1000)
        )

    @staticmethod
    def create_anthropic_client(model="claude-3-sonnet-20240229", **kwargs):
        """Crear cliente de Anthropic"""
        from langchain.chat_models import ChatAnthropic

        Config.validate()

        return ChatAnthropic(
            model=model,
            anthropic_api_key=Config.ANTHROPIC_API_KEY,
            temperature=kwargs.get("temperature", 0.7),
            max_tokens=kwargs.get("max_tokens", 1000)
        )

# Ejemplo de uso
llm = LLMClientFactory.create_openai_client()
response = llm.predict("Hola, preséntate")
print(response)

4. Configuración para múltiples entornos

Para proyectos grandes, es posible que se necesiten diferentes configuraciones de entorno:

Archivos.envespecíficos del entorno

# .env.development (开发环境)
OPENAI_API_KEY=sk-dev-key
APP_ENV=development
DEBUG=true

# .env.production (生产环境)
OPENAI_API_KEY=sk-prod-key
APP_ENV=production
DEBUG=false

Cargar dinámicamente la configuración del entorno

# config_manager.py
import os
from pathlib import Path
from dotenv import load_dotenv

class ConfigManager:
    """配置管理器"""

    def __init__(self, env=None):
        self.env = env or os.getenv("APP_ENV", "development")
        self.load_config()

    def load_config(self):
        """加载配置"""
        # 先加载通用配置
        load_dotenv(dotenv_path=Path('.') / '.env')

        # 加载环境特定配置
        env_file = Path('.') / f'.env.{self.env}'
        if env_file.exists():
            load_dotenv(dotenv_path=env_file, override=True)

        # 加载本地覆盖配置(不提交到Git)
        local_file = Path('.') / f'.env.{self.env}.local'
        if local_file.exists():
            load_dotenv(dotenv_path=local_file, override=True)

    def get(self, key, default=None):
        """获取配置值"""
        return os.getenv(key, default)

# 使用示例
config = ConfigManager(env="development")
print(f"当前环境: {config.get('APP_ENV')}")
print(f"API Key: {config.get('OPENAI_API_KEY')[:10]}...")  # 只显示前10个字符

5. Rotación y monitoreo de claves

Para entornos de producción, se recomienda implementar rotación y monitoreo de claves:

# key_manager.py
import os
import time
from datetime import datetime, timedelta

class APIKeyManager:
    """API Key 管理器"""

    def __init__(self):
        self.keys = {}
        self.key_history = []
        self.load_keys()

    def load_keys(self):
        """加载 API Keys"""
        # 可以从环境变量、数据库或密钥管理服务加载
        self.keys = {
            "openai": {
                "current": os.getenv("OPENAI_API_KEY"),
                "previous": os.getenv("OPENAI_API_KEY_PREVIOUS"),
                "created_at": datetime.now(),
                "rotation_days": 30  # 30天轮换一次
            },
            "anthropic": {
                "current": os.getenv("ANTHROPIC_API_KEY"),
                "previous": None,
                "created_at": datetime.now(),
                "rotation_days": 30
            }
        }

    def get_key(self, service):
        """获取当前可用的 Key"""
        key_info = self.keys.get(service)
        if not key_info:
            raise ValueError(f"未配置服务 {service} 的 API Key")

        # 检查是否需要轮换
        if self.should_rotate(key_info):
            self.rotate_key(service)

        return key_info["current"]

    def should_rotate(self, key_info):
        """检查是否需要轮换 Key"""
        rotation_days = key_info.get("rotation_days", 30)
        created_at = key_info.get("created_at", datetime.now())

        age = datetime.now() - created_at
        return age.days >= rotation_days

    def rotate_key(self, service):
        """轮换 API Key"""
        # 在实际应用中,这里会从密钥管理服务获取新 Key
        print(f"轮换 {service} 的 API Key...")

        key_info = self.keys[service]
        key_info["previous"] = key_info["current"]
        # 这里应该从安全的地方获取新 Key
        # key_info["current"] = get_new_key_from_vault(service)
        key_info["created_at"] = datetime.now()

        # 记录历史
        self.key_history.append({
            "service": service,
            "rotated_at": datetime.now(),
            "old_key": key_info["previous"][:10] + "..." if key_info["previous"] else None
        })

# 使用示例
key_manager = APIKeyManager()
openai_key = key_manager.get_key("openai")
print(f"OpenAI Key: {openai_key[:10]}...")

Herramientas de desarrollo recomendadas

Elegir las herramientas de desarrollo adecuadas puede aumentar considerablemente la eficiencia del desarrollo. A continuación se presentan algunas herramientas recomendadas.

1. Editor de código/IDE

Visual Studio Code (recomendado)

Dirección de descarga:https://code.visualstudio.com/

Extensiones recomendadas:

  • Python: soporte del lenguaje Python
  • Pylance: servidor de lenguaje Python avanzado
  • Jupyter: soporte de cuadernos Jupyter
  • GitLensMejoras de Git
  • PrettierFormateo de código
  • Code Spell CheckerRevisión ortográfica
  • Rainbow CSVResaltado de archivos CSV
  • Thunder ClientHerramienta de prueba de API

Configuración de VS Code(.vscode/settings.json):

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": [
        "--line-length",
        "88"
    ],
    "python.testing.pytestEnabled": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "always"
        }
    },
    "files.exclude": {
        "**/__pycache__": true,
        "**/.pytest_cache": true,
        "**/.venv": true,
        "**/venv": true
    }
}

PyCharm (Edición Profesional)

Dirección de descarga:https://www.jetbrains.com/pycharm/

Características:

  • IDE profesional de Python
  • Potentes funciones de depuración
  • Integración de herramientas de base de datos
  • Soporte para computación científica

2. Control de versiones: Git

Git es una herramienta de control de versiones indispensable.

Configuración básica:

# 配置用户信息
git config --global user.name "你的姓名"
git config --global user.email "你的邮箱"

# 配置默认编辑器(可选)
git config --global core.editor "code --wait"

# 创建 Git 仓库
cd ai-agent-project
git init

# 添加所有文件
git add .

# 提交
git commit -m "初始提交:AI Agent 项目"

# 连接到远程仓库(如 GitHub)
git remote add origin https://github.com/你的用户名/ai-agent-project.git
git branch -M main
git push -u origin main

3. Herramientas de depuración

Depurador de Python (pdb)

# 在代码中插入断点
import pdb

def complex_function(x):
    pdb.set_trace()  # 这里会进入调试器
    result = x * 2
    return result

# 常用 pdb 命令:
# n(ext) - 执行下一行
# s(tep) - 进入函数
# c(ontinue) - 继续执行
# l(ist) - 显示代码
# p(rint) - 打印变量值
# q(uit) - 退出调试器

Configuración de depuración de VS Code

.vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        },
        {
            "name": "Python: 测试",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/tests",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

4. Herramientas de prueba

pytest

# tests/test_agent.py
import pytest
from src.agents.base_agent import BaseAgent

def test_agent_initialization():
    """测试 Agent 初始化"""
    agent = BaseAgent(name="测试Agent")
    assert agent.name == "测试Agent"
    assert agent.messages == []

def test_agent_add_message():
    """测试添加消息"""
    agent = BaseAgent()
    agent.add_message("user", "你好")

    assert len(agent.messages) == 1
    assert agent.messages[0]["role"] == "user"
    assert agent.messages[0]["content"] == "你好"

Ejecutar pruebas:

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_agent.py

# 运行特定测试函数
pytest tests/test_agent.py::test_agent_initialization

# 显示详细输出
pytest -v

# 显示覆盖率报告
pytest --cov=src

5. Calidad de código y formato

black (formateo de código)

# 格式化所有 Python 文件
black .

# 检查哪些文件需要格式化
black --check .

# 格式化单个文件
black src/agents/base_agent.py

flake8 (revisión de código)

# 检查代码质量
flake8 src/

# 忽略特定错误
flake8 --ignore=E501,W503 src/

# 显示错误统计
flake8 --statistics src/

pre-commit (gancho de Git)

Crear.pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        args: [--max-line-length=88]

Instalar pre-commit:

pip install pre-commit
pre-commit install

6. Herramientas de documentación

Jupyter Notebook

Para experimentos y documentación:

# 启动 Jupyter
jupyter notebook

# 或使用 JupyterLab
jupyter lab

MkDocs (generación de documentación)

Creardocs/directorios ymkdocs.yml:

site_name: AI Agent 项目文档
site_url: https://your-project.com
nav:
  - 首页: index.md
  - API文档: api.md
  - 使用指南: guide.md
theme: readthedocs

Generar documentación:

# 安装 MkDocs
pip install mkdocs mkdocs-material

# 本地预览
mkdocs serve

# 构建文档
mkdocs build

7. Herramientas de contenedorización (opcional)

Docker

Dockerfile:

FROM python:3.9-slim

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY src/ ./src/
COPY .env.example .env

# 设置环境变量
ENV PYTHONPATH=/app

# 运行应用
CMD ["python", "src/main.py"]

docker-compose.yml:

version: '3.8'

services:
  ai-agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

8. Monitoreo y registro

loguru (biblioteca de registros)

from loguru import logger
import sys

# 配置日志
logger.remove()  # 移除默认处理器
logger.add(
    sys.stderr,
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
    level="INFO"
)

logger.add(
    "logs/app_{time}.log",
    rotation="500 MB",  # 每500MB轮转
    retention="30 days",  # 保留30天
    compression="zip",  # 压缩旧日志
    level="DEBUG"
)

# 使用日志
logger.info("应用启动")
logger.debug(f"配置加载: {config}")
logger.error("API调用失败", exc_info=True)
Otras extensiones