[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 模块的关键组件功能做了介绍。请求处理流程和策略模式设计分别借助流程图和类图，生动展现系统工作原理与策略设计思路。

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

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

下期预告

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

相关推荐
悟空码字几秒前
SpringBoot + Redis分布式锁深度剖析，性能暴涨的秘密全在这里
java·spring boot·后端
Toky丶1 分钟前
【文献阅读】ARB-LLM: Alternating Refined Binarizations for Large Language Models
人工智能·语言模型·自然语言处理
奋进的芋圆2 分钟前
Spring Boot中实现定时任务
java·spring boot·后端
海奥华24 分钟前
Golang Channel 原理深度解析
服务器·开发语言·网络·数据结构·算法·golang
Jasmine_llq4 分钟前
《P3200 [HNOI2009] 有趣的数列》
java·前端·算法·线性筛法（欧拉筛）·快速幂算法（二进制幂）·勒让德定理（质因子次数统计）·组合数的质因子分解取模法
斯外戈的小白4 分钟前
【NLP】Hugging Face使用指南
人工智能·自然语言处理
victory04315 分钟前
关于深度学习的重要库 transformer
人工智能·深度学习·transformer
代码游侠6 分钟前
学习笔记——MQTT协议
开发语言·笔记·php
love530love6 分钟前
Flash Attention 2.8.3 在 Windows + RTX 3090 上成功编译与运行复盘笔记（2026年1月版）
人工智能·windows·笔记·python·flash_attn·flash attention·z-image
虹科网络安全6 分钟前
艾体宝洞察 | “顶会”看安全（四）：Black hat-揭示 PyTorch 中 TorchScript 引擎的潜在风险
人工智能·pytorch·安全
热门推荐
01GitHub 镜像站点02安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）03Linux下V2Ray安装配置指南04Labelme从安装到标注：零基础完整指南05手把手教你通过Gemini3 pro 学生认证，白用一年，手慢无！06GitLab 零基础入门指南：从安装到项目管理全流程07jdk21下载、安装（Windows、Linux、macOS）08【踩坑笔记】50系显卡适配的 PyTorch 安装09UV安装并设置国内源102025-04-03 Latex学习1——本地配置Latex + VScode环境