技能简介

cmdop-llm 是一款框架无关的 Python 多提供商 LLM 调用库，内置统一的 LLMClient、向量嵌入、结构化抽取与修复、多模态（视觉/图像生成/编辑）、翻译、模型路由、成本追踪等完整能力，并额外提供一个基于 Pydantic AI 的 Agent Harness，方便快速搭建 AI Agent 应用。

它的核心理念是：不绑定任何框架，不引入 Django 等重型依赖，通过一致化的 API 同时调用 OpenAI、OpenRouter、Anthropic、Gemini 等 57 家模型供应商，并在调用层实现模型的智能路由、成本归因和请求日志留存。

核心能力

• 多模型统一接口：只需学会 LLMClient 一套 API，即可调用 57+ 模型供应商，支持 Chat Completion、Embedding、Vision、Image Gen/Edit、Translation 等全模态
• 结构化抽取与修复：基于 Pydantic 模型定义输出结构，自动完成 LLM 输出 → Pydantic 实例的转换，并支持抽取失败时的自动修复重试
• 模型路由（LLMRouter）：通过 Model Catalog 按角色（role）而非具体模型 ID 发请求，由路由器自动选择最合适的模型，支持多级回退链
• 成本追踪：内置 Token 用量和 API 成本统计，每次调用均可追溯费用来源和用量明细
• Pydantic AI Agent Harness：内置轻量级 Agent 运行框架，支持 Tool 调用、对话状态管理和多轮交互，开箱即用
• 零框架依赖：纯库形式存在，无 Django、无 FastAPI 强依赖，业务方可自由集成到任意技术栈
• 结构化输出修复：当 LLM 输出格式偏差时，自动触发修复流程，提升结构化抽取成功率
• 环境变量配置：支持通过环境变量配置各供应商凭据，生产部署极为便捷

安装配置

环境要求

• Python 3.12 及以上版本
• 推荐使用虚拟环境（venv 或 conda）隔离依赖

安装命令

pip install cmdop-llm

如需 Pydantic AI Agent 功能：

pip install cmdop-llm # Agent 模块已包含在主包中

配置凭据

方式一：代码内直接传参（优先级最高）

from cmdop_llm import LLMClient

client = LLMClient(apikey_openrouter="your-key") response = client.chat_completion( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], ) print(response.content)

方式二：环境变量（推荐生产使用）

export OPENROUTER_API_KEY="your-openrouter-key" export OPENAI_API_KEY="your-openai-key" export ANTHROPIC_API_KEY="your-anthropic-key"

方式三：配置对象注入（无框架依赖）

from cmdop_llm import LLMConfig, set_config

set_config( LLMConfig( project_name="my-service", api_keys={"openrouter": "your-key"}, ) )

使用步骤

步骤一：初始化客户端

from cmdop_llm import LLMClient

自动从环境变量读取所有已配置的 API Key

client = LLMClient()

步骤二：发送聊天请求

response = client.chat_completion( model="openai/gpt-4o-mini", messages=[ {"role": "system", "content": "你是一个专业的技术顾问。"}, {"role": "user", "content": "什么是 RAG 系统？"} ], temperature=0.7, max_tokens=500 ) print(response.content)

步骤三：结构化抽取（以产品信息为例）

from pydantic import BaseModel from cmdop_llm import LLMRouter, extract_many

class Product(BaseModel): name: str price: float currency: str = "USD"

router = LLMRouter()

从文本中抽取结构化信息

text = "罗技 MX Master 3S 无线鼠标，售价 599 元" product = router.parse(schema=Product, text=text) print(product.name, product.price, product.currency)

批量抽取

products = extract_many(Product, [ "机械键盘：899 元", "4K 显示器 2999 元" ]) for p in products: print(p.name, p.price)

步骤四：向量嵌入搜索

from cmdop_llm import embed_fast

vector = embed_fast("语义搜索的目标文本")

返回标准化的向量，可用于向量数据库相似度检索

步骤五：使用 Pydantic AI Agent Harness（多轮对话 + Tool）

from cmdop_llm.agent import Agent from pydantic import BaseModel

class WeatherOutput(BaseModel): city: str temperature: float condition: str

agent = Agent( model="openai/gpt-4o", output_type=WeatherOutput, )

result = agent.run("北京今天天气怎么样？") print(result.city, result.temperature, result.condition)

步骤六：模型路由（按角色自动选择）

from cmdop_llm.catalog import ModelRole

router = LLMRouter()

按角色路由：fast 模型处理简单查询，smart 模型处理复杂推理

router.route(role=ModelRole.FAST, query="今天星期几？") router.route(role=ModelRole.SMART, query="请解释量子纠缠的原理")

适用场景

• 场景一：多供应商模型统一管理 企业同时采购了 OpenAI、Anthropic、DeepSeek 等多个供应商的 API，通过 cmdop-llm 统一接口接入，新增供应商无需改动业务代码，仅需配置新的 API Key。

• 场景二：低成本模型路由与降级 简单任务（如摘要、翻译）自动路由到 GPT-4o-mini 等低成本模型，复杂推理任务路由到 GPT-4o，在保证效果的同时优化 API 成本。

• 场景三：结构化数据抽取流水线 AI 应用需要从非结构化文本（合同、简历、票据）中抽取结构化字段，cmdop-llm 的 parse + extract_many 可以批量处理，配合修复机制提升准确率。

• 场景四：快速搭建 AI Agent 原型 无需引入 LangChain 等重型框架，直接用 cmdop_llm.agent 的 Agent Harness，几行代码即可实现多轮对话 + Tool 调用的 Agent 原型。

• 场景五：AI 能力审计与成本归因 开发阶段需要记录每次 LLM 调用的模型、用量、成本，cmdop-llm 内置的追踪机制可以导出完整日志，方便财务分析和 SLA 监控。

适用人群

• 全栈工程师：需要快速集成 LLM 能力到现有产品中，不想引入重型 LangChain 依赖
• AI 应用开发者：需要多模型切换、模型路由和结构化输出等高级能力
• AI 产品经理：需要理解 LLM 调用成本和用量数据，优化产品 AI 成本结构
• 研究团队：需要统一调用多种模型进行实验对比，不需要框架绑定

工作原理

cmdop-llm 的架构分为三层：

传输层（Transport）：每家模型供应商对应一个 Adapter，将各自的 API 差异（认证方式、请求格式、响应解析）封装为统一的内部接口。添加新供应商只需实现对应 Adapter，无需改动上层业务代码。

路由层（Router）：Model Catalog 维护一份角色到模型的映射表（如 FAST = GPT-4o-mini/Claude-Haiku，SMART = GPT-4o/Claude-3-Opus）。调用方指定角色而非具体模型 ID，Router 根据配置的回退链依次尝试，找到可用模型后返回结果。

应用层（Client/Harness）：LLMClient 提供 chat_completion、embed、parse 等统一 API；Agent Harness 在 Client 基础上增加 Tool 注册、对话状态管理和多轮循环控制，实现完整的 Agent 交互逻辑。

官方链接

• PyPI 主页：https://pypi.org/project/cmdop-llm/
• GitHub 仓库：https://github.com/commandoperator/cmdop-llm