跳至主要內容

第2483篇：AI系统的跨团队协作——多团队共建AI系统的工程规范

老张2026/4/30大约 7 分钟

第2483篇：AI系统的跨团队协作——多团队共建AI系统的工程规范

适读人群：技术负责人、AI工程师、架构师 | 阅读时长：约13分钟 | 核心价值：建立多团队共建AI系统的工程规范和协作边界，避免失控

我见过太多 AI 项目死在协作上，而不是死在技术上。

有一个项目，三个团队同时在做：平台团队负责模型服务，业务团队负责应用层，数据团队负责训练数据和评估。三个团队都很能干，但半年之后项目陷入了混乱。

问题出在哪？

平台团队改了模型接口返回的格式，没通知业务团队，业务线上出了 bug；数据团队改了评估数据集的标注规范，没同步给模型团队，模型效果评分突然变差；业务团队直接绕过平台团队，私自调了一个外部模型 API，没有经过安全审计。

技术能力不是问题，协作规范是问题。

一、多团队 AI 系统的协作挑战

AI 系统和传统软件系统的多团队协作有几个特殊的挑战：

挑战一：边界模糊。模型效果差，是模型问题还是 Prompt 写得不好？是训练数据质量问题还是业务需求没描述清楚？这些问题很难干净地归属到一个团队。

挑战二：变更影响难以预测。传统代码改个函数签名，影响面一眼能看出来。但模型版本更新、训练数据变化，对下游的影响往往是隐性的、非线性的。

挑战三：评估标准不统一。平台团队用 benchmark 评估模型质量，业务团队用用户满意度评估，数据团队用标注一致性评估。三个团队说的"好"可能是不同的"好"。

挑战四：实验和生产的边界模糊。AI 系统经常有"灰度实验"、"A/B 测试"，在多团队环境下，谁批准实验，谁监控实验，谁决定回滚，需要非常清晰的规范。

二、团队边界划分原则

在动手写规范之前，先要把团队边界划清楚。

每个团队的核心边界：

团队拥有什么不能越界的是
数据团队数据 Pipeline、标注规范、特征仓库不直接修改模型权重、不修改推理服务
模型平台团队模型服务、推理 API、向量库不直接改业务 Prompt、不改数据标注逻辑
AI应用团队Prompt 模板、RAG 流程、Agent 编排不绕过平台团队直调底层模型
业务产品团队功能需求、用户数据分析、业务指标不擅自改动 AI 逻辑，需提需求而非改代码

三、工程规范：接口契约管理

多团队之间最核心的协作机制是接口契约（Contract）。

任何跨团队的接口变更，都必须走契约变更流程，不能单方面修改。

3.1 模型服务接口契约定义

/**
 * 模型推理服务接口契约
 * 版本: v2.3.0
 * 维护团队: 模型平台团队
 * 消费团队: AI应用团队
 * 最后更新: 2024-01-15
 * 变更通知: model-platform@company.com
 */
@ApiVersion("2.3")
public interface ModelInferenceContract {

    /**
     * 文本推理接口
     * 
     * 破坏性变更清单（需要提前30天通知）：
     * - 删除响应字段
     * - 修改字段类型
     * - 修改错误码含义
     * 
     * 非破坏性变更（提前7天通知）：
     * - 新增可选请求字段
     * - 新增响应字段
     * - 新增错误码
     */
    InferenceResponse infer(InferenceRequest request);

    /**
     * 获取当前契约版本
     * 消费方应在启动时验证版本兼容性
     */
    ContractVersion getVersion();
}

@Data
@Builder
public class InferenceRequest {
    @NotNull
    private String model;           // 模型名称，如 "gpt-4o", "glm-4"
    
    @NotNull
    @Size(max = 100000)
    private List<Message> messages;
    
    @Min(1) @Max(4096)
    private Integer maxTokens;      // 不设置则用模型默认值
    
    @DecimalMin("0.0") @DecimalMax("2.0")
    private Double temperature;
    
    private String requestId;       // 调用方生成的请求 ID，用于追踪
    
    // v2.3 新增：可选的结构化输出格式
    private ResponseFormat responseFormat;  // 新增字段，老版本消费方忽略即可
}

@Data
@Builder
public class InferenceResponse {
    @NotNull
    private String requestId;       // 回传调用方的请求 ID
    
    @NotNull
    private String content;         // 模型输出内容
    
    @NotNull
    private UsageInfo usage;        // Token 使用情况
    
    @NotNull
    private String modelVersion;    // 实际使用的模型版本（可能有影子流量）
    
    private String finishReason;    // stop / length / content_filter
    
    @NotNull
    private Instant processedAt;    // 服务端处理完成时间
}

3.2 契约测试框架

光定义契约不够，还要用自动化测试来保证契约不被悄悄破坏：

/**
 * 消费方契约测试
 * AI应用团队维护这个测试，在每次模型平台发布新版本时运行
 */
@ContractTest
@Slf4j
public class ModelInferenceContractTest {

    private final ModelInferenceClient client = new ModelInferenceClient();

    @Test
    @DisplayName("契约测试: 基本推理接口结构正确")
    void shouldReturnValidResponseStructure() {
        InferenceRequest request = InferenceRequest.builder()
            .model("gpt-4o-mini")
            .messages(List.of(Message.user("hello")))
            .maxTokens(100)
            .requestId(UUID.randomUUID().toString())
            .build();

        InferenceResponse response = client.infer(request);

        // 验证响应结构（不依赖具体内容）
        assertThat(response.getRequestId()).isNotBlank();
        assertThat(response.getContent()).isNotNull();
        assertThat(response.getUsage()).isNotNull();
        assertThat(response.getUsage().getPromptTokens()).isGreaterThanOrEqualTo(0);
        assertThat(response.getUsage().getCompletionTokens()).isGreaterThanOrEqualTo(0);
        assertThat(response.getModelVersion()).isNotBlank();
        assertThat(response.getProcessedAt()).isNotNull();
    }

    @Test
    @DisplayName("契约测试: requestId 必须回传")
    void shouldEchoRequestId() {
        String requestId = "test-" + UUID.randomUUID();
        InferenceRequest request = InferenceRequest.builder()
            .model("gpt-4o-mini")
            .messages(List.of(Message.user("test")))
            .requestId(requestId)
            .build();

        InferenceResponse response = client.infer(request);
        assertThat(response.getRequestId()).isEqualTo(requestId);
    }

    @Test
    @DisplayName("契约测试: 超大输入应返回 400 错误码")
    void shouldReturn400ForOversizedInput() {
        String hugeContent = "x".repeat(200000);
        InferenceRequest request = InferenceRequest.builder()
            .model("gpt-4o-mini")
            .messages(List.of(Message.user(hugeContent)))
            .build();

        assertThatThrownBy(() -> client.infer(request))
            .isInstanceOf(ModelApiException.class)
            .satisfies(e -> assertThat(((ModelApiException) e).getErrorCode())
                .isEqualTo("INPUT_TOO_LONG"));
    }

    @Test
    @DisplayName("契约测试: 版本兼容性检查")
    void shouldBeCompatibleWithExpectedVersion() {
        ContractVersion version = client.getVersion();
        
        // 消费方声明自己期望的最低版本
        ContractVersion minimumRequired = ContractVersion.of(2, 0, 0);
        assertThat(version.isCompatibleWith(minimumRequired))
            .as("模型服务版本 %s 应兼容消费方最低要求 %s", version, minimumRequired)
            .isTrue();
    }
}

四、变更管理流程

4.1 变更影响评估

@Service
@Slf4j
public class ChangeImpactAssessmentService {

    private final ContractRegistry contractRegistry;
    private final TeamNotificationService notificationService;

    // 提交变更申请时，自动评估影响范围
    public ChangeImpactReport assess(ChangeRequest changeRequest) {
        List<ImpactedTeam> impactedTeams = new ArrayList<>();
        List<String> breakingChanges = new ArrayList<>();
        List<String> nonBreakingChanges = new ArrayList<>();

        // 找出所有消费这个接口的团队
        List<ContractConsumer> consumers = contractRegistry
            .getConsumers(changeRequest.getInterfaceId());

        for (Change change : changeRequest.getChanges()) {
            if (change.isBreaking()) {
                breakingChanges.add(change.getDescription());
                
                // 通知所有消费团队
                for (ContractConsumer consumer : consumers) {
                    impactedTeams.add(ImpactedTeam.builder()
                        .teamName(consumer.getTeamName())
                        .contactEmail(consumer.getContactEmail())
                        .impactLevel(ImpactLevel.HIGH)
                        .requiredAction("必须更新消费代码后才能升级")
                        .deadline(changeRequest.getPlannedDate().minusDays(7))
                        .build());
                }
            } else {
                nonBreakingChanges.add(change.getDescription());
            }
        }

        ChangeImpactReport report = ChangeImpactReport.builder()
            .changeRequestId(changeRequest.getId())
            .breakingChanges(breakingChanges)
            .nonBreakingChanges(nonBreakingChanges)
            .impactedTeams(impactedTeams)
            .minimumNoticeDays(breakingChanges.isEmpty() ? 7 : 30)
            .build();

        // 自动发送通知邮件
        if (!impactedTeams.isEmpty()) {
            notificationService.notifyChangeImpact(report);
        }

        return report;
    }
}

五、共享质量标准

多团队协作最容易出问题的是"大家对质量的理解不一样"。解决方案是建立共享质量仪表板：

@RestController
@RequestMapping("/api/ai-quality")
public class SharedQualityDashboardController {

    @GetMapping("/metrics/cross-team")
    public CrossTeamQualityMetrics getCrossTeamMetrics(
            @RequestParam String projectId,
            @RequestParam String period) {

        return CrossTeamQualityMetrics.builder()
            // 数据团队的贡献指标
            .dataMetrics(DataMetrics.builder()
                .labelingAccuracy(0.96)
                .featureCoverage(0.89)
                .dataFreshness("T+1")
                .build())
            
            // 模型平台团队的贡献指标
            .modelMetrics(ModelMetrics.builder()
                .benchmarkScore(0.84)
                .p99Latency(320)   // ms
                .availability(0.9997)
                .build())
            
            // AI应用团队的贡献指标
            .applicationMetrics(ApplicationMetrics.builder()
                .promptQualityScore(0.88)
                .ragRetrievalPrecision(0.81)
                .agentSuccessRate(0.76)
                .build())
            
            // 业务产品团队的结果指标
            .businessMetrics(BusinessMetrics.builder()
                .userSatisfactionScore(4.2)
                .taskCompletionRate(0.83)
                .aiAdoptionRate(0.61)
                .build())
            
            .lastUpdated(Instant.now())
            .build();
    }
}

这个仪表板对所有团队公开。每个团队都能看到自己的贡献和其他团队的贡献，以及最终的业务结果。

这有两个好处：一是问题出了，责任定位更容易；二是大家都能看到业务结果，有共同的目标感。

六、工程规范落地的关键

最后说一个执行层面的经验：规范本身没用，规范的执行机制才有用。

我们团队做了几件事让规范真正落地：

一是把规范检查嵌入 CI/CD。接口变更必须有契约测试覆盖，没有覆盖的 PR 不能合并。这是强制的，不是靠人的自觉。

二是建立跨团队的 AI 工程师联席会。每两周一次，每个团队出一个人，专门讨论跨团队的接口变更、质量问题、改进计划。

三是出了问题先复盘流程，不追人的责任。如果一次事故是因为跨团队通知没到位，复盘的重点应该是"通知机制哪里有漏洞"，而不是"谁没通知谁"。追责文化会让人隐瞒问题，blameless 文化才能让问题浮出水面。

协作是软件工程里最难的部分。但把这件事做好，效果是倍增的。

编辑此页
最近更新:
贡献者: xiaozhangge