[Day7] contract-ai深度剖析：大模型适配项目的架构设计与策略实现

一条咸鱼_SaltyFish2026-01-07 8:56

大模型适配项目全解析

目录

  1. 模块概述
  2. 架构设计
  3. 项目目录结构
  4. 核心组件说明
    • [ai - feign - client 模块](#ai - feign - client 模块)
    • [ai - core 模块](#ai - core 模块)
  5. 请求处理流程
  6. 策略模式设计
  7. 扩展
  8. 开发日志与测试计划
  9. 总结与下期预告

模块概述

本项目聚焦于大模型适配相关工作，具备大模型适配、格式转换以及第三方集成等功能。具体需求为提供大模型能力接口，且要实现模型代码与配置参数的完全解耦。在设计方面，通过提供统一的 AI 对话接口，以支持多种 AI 模型及服务提供商的集成。该项目运用策略模式达成模型路由，利用模型名称作为路由键，将请求分发给不同的 AI 提供商。

架构设计

核心设计

  • 固定契约 ：以 chat(ChatRequest) 方法签名作为稳定的外部接口，如同生活中快递服务的固定取件方式，无论哪家快递公司，都遵循一定的流程来取件，这个接口就是系统对外交互的标准流程。
  • 策略模式：基于模型名的路由机制，实现对多个 AI 提供商的支持。就好比不同的快递公司（AI 提供商），根据包裹的目的地（模型名）选择合适的运输路线（策略）。
  • 服务发现：基于 Nacos 的服务发现与 Feign 客户端集成，方便系统查找和调用所需的服务。
  • 模块分离：将核心逻辑与外部接口完全分离，确保系统各部分职责清晰，互不干扰。

整体架构图

外部AI服务
contract - ai 服务
外部调用层
Feign客户端层
策略层
HTTP请求
根据模型路由
客户端应用
ChatController
ChatService
AiStrategyRouter
DeepSeek策略
Iflow策略
GLM - Vision策略
AiClient
转换器
DeepSeek API
Iflow API
GLM API

模块划分

contract - ai
ai - core
ai - feign - client
依赖
使用
调用
实现
核心服务
DTO定义
AiClient接口
REST控制器
策略实现
核心配置
枚举定义

项目目录结构

复制代码 
contract - ai/
├── pom.xml                                    # 父级 Maven 配置
│
├── ai - feign - client/                          # Feign 客户端模块
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/com/contract/ai/feign/
│       │   │   ├── client/                   # Feign 客户端接口
│       │   │   │   ├── AiClient.java        # 统一 AI 调用接口
│       │   │   │   └── AiClientConfiguration.java
│       │   │   │
│       │   │   ├── dto/                      # 数据传输对象
│       │   │   │   ├── ChatRequest.java     # 通用请求 DTO
│       │   │   │   ├── ChatResponse.java    # 通用响应 DTO
│       │   │   │   ├── ApiResponse.java     # API 响应包装
│       │   │   │   ├── deepseek/            # DeepSeek 专用 DTO
│       │   │   │   └── glm/                 # GLM 专用 DTO
│       │   │   │
│       │   │   ├── convertor/                # 平台转换器
│       │   │   │   ├── PlatformConvertor.java
│       │   │   │   ├── DeepSeekConvertor.java
│       │   │   │   └── GlmConvertor.java
│       │   │   │
│       │   │   ├── enums/                    # 枚举定义
│       │   │   │   ├── PlatFormType.java
│       │   │   │   └── ModelType.java
│       │   │   │
│       │   │   ├── properties/               # 配置属性
│       │   │   │   └── AiClientProperties.java
│       │   │   │
│       │   │   ├── util/                     # 工具类
│       │   │   │   ├── ImageBase64Validator.java
│       │   │   │   └── ImageCompressorWithThumbnailator.java
│       │   │   │
│       │   │   └── config/                   # 自动配置
│       │   │       ├── SimpleAiClientConfiguration.java
│       │   │       └── CompleteAiClientConfiguration.java
│       │   │
│       │   └── resources/
│       │
│       └── test/                             # 单元测试
│
├── ai - core/                                  # 核心服务模块
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/com/contract/ai/core/
│       │   │   ├── AiCoreApplication.java   # 应用启动类
│       │   │   │
│       │   │   ├── controller/               # REST 控制器
│       │   │   │   └── ChatController.java
│       │   │   │
│       │   │   ├── service/                  # 服务层
│       │   │   │   ├── ChatService.java
│       │   │   │   └── FileStorageService.java
│       │   │   │
│       │   │   ├── strategy/                 # 策略模式实现
│       │   │   │   ├── impl/
│       │   │   │   │   ├── deepseek/
│       │   │   │   │   │   ├── DeepSeekAiStrategy.java
│       │   │   │   │   │   └── DeepSeekConfiguration.java
│       │   │   │   │   ├── iflow/
│       │   │   │   │   │   └── IflowAiStrategy.java
│       │   │   │   │   └── glm - vision/
│       │   │   │   │       └── GlmVisionAiStrategy.java
│       │   │   │   └── ...
│       │   │   │
│       │   │   ├── registry/                 # 策略注册器
│       │   │   │   └── AiStrategyRegistry.java
│       │   │   │
│       │   │   ├── config/                   # 核心配置
│       │   │   │   ├── StrategyAutoConfiguration.java
│       │   │   │   ├── AiExceptionAutoConfiguration.java
│       │   │   │   └── GlmVisionStrategyPostProcessor.java
│       │   │   │
│       │   │   ├── exception/                # 异常处理
│       │   │   │   ├── AiGlobalExceptionHandler.java
│       │   │   │   ├── AiException.java
│       │   │   │   └── AiErrorCode.java
│       │   │   │
│       │   │   └── util/                     # 工具类
│       │   │       └── FileToBase64Converter.java
│       │   │
│       │   └── resources/
│       │       ├── application.yml           # 主配置文件
│       │       └── application - xxx.yml
│       │
│       └── test/                             # 集成测试
│           ├── integration/
│           └── strategy/

核心组件说明

1. ai - feign - client 模块

该模块定义了与外部 AI 服务交互的统一接口。

组件 说明
AiClient 统一的 Feign 客户端接口，定义 chat(ChatRequest) 方法
ChatRequest/ChatResponse 通用请求响应 DTO
PlatformConvertor 平台转换器接口，处理不同平台的数据转换
PlatFormType 支持的 AI 平台枚举
ModelType 支持的模型类型枚举

2. ai - core 模块

该模块包含核心业务逻辑和策略实现。

组件 说明
ChatController REST API 入口，提供统一的聊天接口
ChatService 核心服务，处理请求验证和路由
AiStrategyRouter 策略路由器，根据模型名选择对应策略
AiStrategyRegistry 策略注册中心，管理所有可用策略
AiGlobalExceptionHandler 全局异常处理器
*AiStrategy 各平台的策略实现类

请求处理流程

外部AI服务 AiClient AiStrategy AiStrategyRouter ChatService ChatController 客户端 外部AI服务 AiClient AiStrategy AiStrategyRouter ChatService ChatController 客户端 POST /api/chat chat(ChatRequest) 参数验证 route(model) 获取策略实例 请求转换 chat(PlatformRequest) HTTP 请求 AI 响应 PlatformResponse 响应转换 ChatResponse ChatResponse JSON 响应

策略模式设计

<<interface>>
AiStrategy
+chat(ChatRequest) : ChatResponse
+getModelName() : String
+getPlatform() : PlatFormType
DeepSeekAiStrategy
+chat(ChatRequest) : ChatResponse
+getModelName() : String
+getPlatform() : PlatFormType
IflowAiStrategy
+chat(ChatRequest) : ChatResponse
+getModelName() : String
+getPlatform() : PlatFormType
GlmVisionAiStrategy
+chat(ChatRequest) : ChatResponse
+getModelName() : String
+getPlatform() : PlatFormType
AiStrategyRegistry
-Map<String, AiStrategy> strategies
+register(AiStrategy)
+getStrategy(String) : AiStrategy

扩展

  1. 创建策略实现类 ：实现 AiStrategy 接口
  2. 添加配置类：定义 Bean 和配置属性
  3. 实现转换器：处理平台特定的数据格式
  4. 注册策略：通过自动配置注册到策略注册中心

模块依赖关系

依赖
依赖
HTTP调用
ai - core
ai - feign - client
其他服务
外部AI服务

开发日志与测试计划

开发日志（流水账）

提供大模型能力接口，需实现模型代码与配置参数完全解耦。可先研究心流平台和普通 deepseek 之间返回值的差异，目前可能只能单平台对接适配，需进一步调研。

对外提供的 Feign API 格式固定，现阶段仅开放 chat 接口，无需上传图片等功能。模块业务可通过不同策略模式支持，如此便能快速对接新模型或更换配置，且不影响接口，接口还能通过 type 切换所需模型或服务提供商（由两个参数控制）。然而，上传功能可能会引发一些问题。

plaintext 复制代码 
对接心流平台
平台: 心流(iflow)
apikey: sk - xxxxxx
model: GLM - 4.6
url: https://apis.iflow.cn/v1/chat/completions    
这是详细文档https://platform.iflow.cn/docs/api - reference

基础实例curl:
curl https://apis.iflow.cn/v1/chat/completions \
-H "Content - Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "xxxxx",
"messages": [
{"role": "system", "content": "你是一个专业的AI助手。"},
{"role": "user", "content": "请介绍一下人工智能的发展历史"}
],
"temperature": 0.7,
"max_tokens": 1000
}'

错误码:
400    请求体错误
解决方法：修改请求体解决
401    API KEY 错误
解决方法：请检查您的 API KEY 是否正确，如没有 API KEY，请先创建 API KEY
404    找不到资源
解决方法：请检查您的请求路径是否正确
429    请求频率过快
解决方法：请稍后重试您的请求
503    服务器内部错误
解决方法：请等待后重试。若问题一直存在，请联系我们解决
504    服务器过载
解决方法：请稍后重试您的请求

注意: 此模型并发只能为1否则会返回429错误


请你按照之前提示词内设计对接这个平台，如果有任何疑问请现在询问我

过程中发现 Feign 注册问题，以及返回结果缺少 convertor 问题。

抽取所有模块的服务发现依赖以统一版本。

测试计划

  1. 测试对话接口的 iflow、dp
  2. 测试图形接口 glm
  3. 测试合同类型
  4. 测试 clause 抽取接口和状态接口
  5. 测试抽取条款日志

所有接口均在 Postman 进行测试，为了确保接口参数正常生效、代码校验均能触发。

总结与下期预告

总结

本文围绕大模型适配项目展开全面阐述。在模块概述部分，明确项目具备大模型适配、格式转换与第三方集成功能，需求是提供解耦模型代码与配置参数的大模型能力接口，通过策略模式实现基于模型名的路由分发。

架构设计层面，核心设计涵盖固定契约、策略模式、服务发现及模块分离。整体架构图直观呈现外部调用层、contract - ai 服务、外部 AI 服务间的交互关系，模块划分清晰展示各模块组成及依赖。

项目目录结构详细罗列各模块及子模块的文件构成，让读者清晰了解代码布局。核心组件说明对 ai - feign - client 和 ai - core 模块的关键组件功能做了介绍。请求处理流程和策略模式设计分别借助流程图和类图，生动展现系统工作原理与策略设计思路。

扩展部分说明项目扩展方式，模块依赖关系图呈现各部分依赖联系。开发日志记录开发过程中的问题与解决思路，测试计划明确需测试的接口及测试要求。

整体而言，完整介绍了项目从设计到实现及测试的全流程，希望能提供一些理解和实践相关技术提供丰富参考。

下期预告

下次将讲述本期未提及的问题，分享解决疑难杂症的经验。

相关推荐
SLD_Allen10 小时前
DRA、MIG与GPU共享的云原生AI实践
人工智能·云原生
木井巳10 小时前
【DFS解决floodfill算法】岛屿的最大面积
java·算法·leetcode·深度优先
用户2986985301410 小时前
免费在线将 PDF 转为 Word：5 款好用的转换工具
人工智能·后端
AIsoft_868810 小时前
按日期查找录音的软件：快速定位历史会议记录
人工智能·智能手机·语音识别
她说可以呀10 小时前
Spring-ai-alibaba视频生成
人工智能·spring·音视频
Luhui Dev10 小时前
几何题配图 API 怎么选？从文本生成到可编辑源文件的接入指南
人工智能·数学·agent·luhuidev
Canace11 小时前
为了给视频里的人脸打码，我让 Claude 做了个 Skill
前端·人工智能
武子康11 小时前
Prompt 之外，生产级 Agent Harness 到底在控制什么
人工智能·llm·agent
林森lsjs11 小时前
完结撒花！Java SE 语法阶段总结！
java·开发语言
lupai11 小时前
短信接口快速接入与调用实战指南
java·开发语言·数据库
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费0800 Debian字符界面如何支持中文092026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片102026 年 AI 大模型 & AI 编程工具实战全总结