같이 연구해요

AI혁신 솔루션센터 개발 여정: 모노레포 아키텍처로 시작하는 엔터프라이즈 플랫폼 구축기

글쓰는 연구원 상티 — Sat, 16 Aug 2025 17:13:36 +0900

프롤로그: 예상치 못한 리더십의 시작

대학원 과정 중 글로컬 대학 선정이라는 예상치 못한 기회가 찾아왔다. AI혁신 솔루션센터 개발 프로젝트의 총괄을 맡게 되면서, 나는 단순한 개발자에서 아키텍트이자 프로젝트 리더가 되어야 했다. 처음에는 막막했다. 여러 프로덕트를 동시에 개발해야 하는 상황에서 어떻게 일관성 있고 확장 가능한 시스템을 구축할 것인가라는 근본적인 질문에 직면했기 때문이다.

1장: 아키텍처의 선택 - 왜 모노레포인가?

문제 정의: 복잡성의 늪

초기 요구사항을 분석하면서 깨달은 것은 이 프로젝트가 단순한 웹 애플리케이션이 아니라는 점이었다.

AI Solution Center 요구사항:
├── 사용자 관리 시스템
├── AI 모델 서빙 플랫폼
├── 데이터 분석 대시보드
├── 실시간 채팅 서비스
├── 문서 관리 시스템
├── API 게이트웨이
└── 관리자 백오피스

각각이 독립적인 서비스로 운영되어야 하지만, 동시에 사용자 인증, 데이터베이스 접근, 로깅, 모니터링 등의 공통 기능을 공유해야 했다. 이때 마이크로서비스 아키텍처와 모노레포 사이에서 고민이 시작되었다.

모노레포 선택의 근거

여러 선택지를 놓고 심사숙고한 끝에 모노레포를 선택했다. 그 이유는 다음과 같았다:

1. 코드 재사용성과 일관성

// 각 서비스에서 동일한 인터페이스 사용
import { BaseEntity, BaseRepository } from '@ai-solution/core/database';
import { JwtAuthGuard, CurrentUser } from '@ai-solution/core/auth';
import { LLMService } from '@ai-solution/core/llm';

2. 의존성 관리의 단순화

{
  "dependencies": {
    "@nestjs/core": "^10.0.0",
    "typeorm": "^0.3.17",
    "passport-jwt": "^4.0.1"
  }
}

모든 서비스가 동일한 버전의 의존성을 사용하여 호환성 문제를 원천 차단했다.

3. 개발 효율성

# 전체 프로젝트 빌드
nx run-many --target=build --all

# 특정 라이브러리 변경 시 영향받는 프로젝트만 빌드
nx affected:build --base=main

Nx 선택의 기술적 배경

Nx를 선택한 것은 단순히 모노레포 도구이기 때문만이 아니었다.

// nx.json 설정
{
  "extends": "@nx/workspace/presets/npm.json",
  "$schema": "./node_modules/@nx/workspace/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"]
    },
    "test": {
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"]
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": ["default", "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)", "!{projectRoot}/tsconfig.spec.json", "!{projectRoot}/jest.config.[jt]s", "!{projectRoot}/src/test-setup.[jt]s", "!{projectRoot}/test-setup.[jt]s", "!{projectRoot}/.eslintrc.json", "!{projectRoot}/eslint.config.js"],
    "sharedGlobals": []
  }
}

Nx의 의존성 그래프 분석과 증분 빌드 기능은 대규모 프로젝트에서 빌드 시간을 획기적으로 줄여준다. 실제로 7개의 서비스와 3개의 코어 라이브러리가 있는 현재 구조에서도 변경된 부분만 빌드하여 전체 빌드 시간을 70% 이상 단축할 수 있었다.

2장: 코어 라이브러리 설계 - 공통 기능의 추상화

아키텍처 설계 원칙

코어 라이브러리를 설계할 때 다음 원칙들을 세웠다:

단일 책임 원칙: 각 라이브러리는 하나의 명확한 책임을 가진다
의존성 역전: 구체적인 구현이 아닌 추상화에 의존한다
개방-폐쇄 원칙: 확장에는 열려있고 수정에는 닫혀있다

libs/core/
├── auth/          # 인증 및 권한 관리
├── database/      # 데이터베이스 추상화
└── llm/           # LLM 프로바이더 통합

core-auth: 보안의 중심축

인증 시스템을 설계하면서 가장 중요하게 생각한 것은 확장성과 보안성이었다. JWT 기반의 무상태 인증을 선택했지만, 동시에 미래의 요구사항 변화에 대비할 수 있도록 설계했다.

// libs/core/auth/src/auth.service.ts
@Injectable()
export class AuthService {
  constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
    private jwtService: JwtService,
    private configService: ConfigService,
  ) {}

  async validateUser(email: string, password: string): Promise<User | null> {
    try {
      const user = await this.userRepository.findOne({
        where: { email, isActive: true },
      });

      if (user && (await user.validatePassword(password))) {
        return user;
      }
      return null;
    } catch (error) {
      throw new UnauthorizedException('Authentication failed');
    }
  }

  async login(email: string, password: string): Promise<LoginResponse> {
    const user = await this.validateUser(email, password);
    if (!user) {
      throw new UnauthorizedException('Invalid credentials');
    }

    // 토큰 생성
    const payload: JwtPayload = {
      sub: user.id,
      email: user.email,
      role: user.role,
    };

    const token = this.jwtService.sign(payload, {
      expiresIn: this.configService.get<string>('JWT_EXPIRES_IN', '1d'),
    });

    // 마지막 로그인 시간 업데이트
    await this.userRepository.update(user.id, {
      lastLoginAt: new Date(),
    });

    return {
      user: {
        id: user.id,
        email: user.email,
        firstName: user.firstName,
        lastName: user.lastName,
        role: user.role,
      },
      token,
    };
  }
}

특히 주목할 점은 패스워드 검증 로직을 User 엔티티 내부로 캡슐화한 것이다:

// libs/core/auth/src/entities/user.entity.ts
@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @Column({ unique: true })
  email!: string;

  @Column()
  @Exclude()
  password!: string;

  @BeforeInsert()
  @BeforeUpdate()
  async hashPassword() {
    if (this.password) {
      const saltRounds = 12;
      this.password = await bcrypt.hash(this.password, saltRounds);
    }
  }

  async validatePassword(password: string): Promise<boolean> {
    return bcrypt.compare(password, this.password);
  }
}

이러한 설계로 비즈니스 로직과 데이터 접근 로직을 분리하면서도, 보안 요구사항을 만족시킬 수 있었다.

core-database: 데이터 접근의 표준화

데이터베이스 레이어를 추상화하면서 가장 고민했던 부분은 반복적인 CRUD 작업을 어떻게 효율적으로 처리할 것인가였다.

// libs/core/database/src/entities/base.entity.ts
export abstract class BaseEntity {
  @PrimaryGeneratedColumn('uuid')
  id!: string;

  @CreateDateColumn({
    type: 'timestamp with time zone',
    default: () => 'CURRENT_TIMESTAMP',
  })
  createdAt!: Date;

  @UpdateDateColumn({
    type: 'timestamp with time zone',
    default: () => 'CURRENT_TIMESTAMP',
    onUpdate: 'CURRENT_TIMESTAMP',
  })
  updatedAt!: Date;

  @DeleteDateColumn({
    type: 'timestamp with time zone',
    nullable: true,
  })
  deletedAt?: Date;
}

BaseEntity를 통해 모든 엔티티가 공통으로 가져야 할 필드들을 정의했다. 특히 소프트 삭제 기능을 기본으로 제공하여 데이터 손실을 방지했다.

// libs/core/database/src/repository/base.repository.ts
export class BaseRepository<T extends BaseEntity> extends Repository<T> {
  async findByIdOrFail(id: string): Promise<T> {
    const entity = await this.findOne({
      where: { id } as FindOptionsWhere<T>,
    });

    if (!entity) {
      throw new Error(`Entity with id ${id} not found`);
    }

    return entity;
  }

  async createAndSave(entityData: DeepPartial<T>): Promise<T> {
    const entity = this.create(entityData);
    return this.save(entity);
  }

  async updateById(id: string, updateData: DeepPartial<T>): Promise<T> {
    const entity = await this.findByIdOrFail(id);
    Object.assign(entity, updateData);
    return this.save(entity);
  }

  async softDeleteById(id: string): Promise<UpdateResult> {
    return this.softDelete(id);
  }

  async bulkCreate(entitiesData: DeepPartial<T>[]): Promise<T[]> {
    const entities = this.create(entitiesData);
    return this.save(entities);
  }
}

BaseRepository를 통해 반복적인 데이터베이스 작업을 표준화했다. 이로 인해 각 서비스에서 비즈니스 로직에만 집중할 수 있게 되었다.

core-llm: AI 기능의 통합

AI 솔루션센터라는 프로젝트 특성상 다양한 LLM 모델을 사용해야 했다. 하지만 각 프로바이더마다 다른 API 형태와 응답 구조를 가지고 있어 이를 통합하는 것이 큰 도전이었다.

// libs/core/llm/src/interfaces/llm-provider.interface.ts
export interface LLMProvider {
  name: string;
  isAvailable(): Promise<boolean>;
  generateCompletion(
    messages: LLMMessage[],
    options?: LLMProviderOptions
  ): Promise<LLMResponse>;
}

export interface LLMMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

export interface LLMResponse {
  content: string;
  usage?: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  provider: string;
}

통합된 인터페이스를 정의한 후, 각 프로바이더별로 구현체를 만들었다:

// libs/core/llm/src/providers/openai.provider.ts
@Injectable()
export class OpenAIProvider implements LLMProvider {
  public readonly name = 'openai';
  private client: OpenAI | null = null;

  constructor(private readonly apiKey?: string) {
    if (this.apiKey) {
      this.client = new OpenAI({ apiKey: this.apiKey });
    }
  }

  async generateCompletion(
    messages: LLMMessage[],
    options: LLMProviderOptions = {}
  ): Promise<LLMResponse> {
    if (!this.client) {
      throw new Error('OpenAI client is not initialized');
    }

    const completion = await this.client.chat.completions.create({
      model: options.model || 'gpt-4o-mini',
      messages: messages.map((msg) => ({
        role: msg.role,
        content: msg.content,
      })),
      temperature: options.temperature ?? 0.7,
      max_tokens: options.maxTokens,
      top_p: options.topP,
    });

    const response = completion.choices[0];
    return {
      content: response.message?.content || '',
      usage: completion.usage ? {
        promptTokens: completion.usage.prompt_tokens,
        completionTokens: completion.usage.completion_tokens,
        totalTokens: completion.usage.total_tokens,
      } : undefined,
      provider: this.name,
    };
  }
}

가장 중요한 부분은 LLMService에서 구현한 자동 페일오버 기능이었다:

// libs/core/llm/src/llm.service.ts
@Injectable()
export class LLMService {
  private providers: Map<string, LLMProvider> = new Map();
  private fallbackProviders: string[] = [];

  async generateCompletion(
    messages: LLMMessage[],
    options: LLMProviderOptions & { provider?: string } = {}
  ): Promise<LLMResponse> {
    const providerName = options.provider || this.defaultProvider;
    const primaryProvider = this.providers.get(providerName);

    try {
      return await this.executeWithRetry(primaryProvider, messages, options);
    } catch (error) {
      // 페일오버 로직
      for (const fallbackName of this.fallbackProviders) {
        if (fallbackName === providerName) continue;

        const fallbackProvider = this.providers.get(fallbackName);
        if (!fallbackProvider) continue;

        try {
          const isAvailable = await fallbackProvider.isAvailable();
          if (!isAvailable) continue;

          return await this.executeWithRetry(fallbackProvider, messages, options);
        } catch (fallbackError) {
          continue;
        }
      }
      throw error;
    }
  }
}

이러한 설계로 OpenAI API가 장애를 겪어도 Claude나 Ollama로 자동 전환되어 서비스 연속성을 보장할 수 있었다.

3장: 실제 서비스 구현 - 이론에서 실전으로

Chat Service: 실시간 대화의 구현

첫 번째로 구현한 서비스는 Chat Service였다. 이는 사용자가 AI와 실시간으로 대화할 수 있는 플랫폼이었다.

// apps/services/chat-service/src/app/app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env.local', '.env'],
    }),
    DatabaseModule.forRoot(),
    AuthModule,
    LLMModule.forRoot({
      defaultProvider: 'openai',
      fallbackProviders: ['claude', 'ollama'],
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

코어 라이브러리들을 조합하여 서비스를 구성하는 과정에서 모노레포의 진가를 확인할 수 있었다. 각 라이브러리가 독립적으로 동작하면서도 seamless하게 통합되었다.

// apps/services/chat-service/src/app/app.controller.ts
@Controller('chat')
export class ChatController {
  constructor(
    private readonly llmService: LLMService,
  ) {}

  @Post('message')
  @UseGuards(JwtAuthGuard)
  async sendMessage(
    @CurrentUser() user: any,
    @Body() body: { message: string; conversationId?: string }
  ) {
    const messages = [
      { role: 'system', content: '당신은 도움이 되는 AI 어시스턴트입니다.' },
      { role: 'user', content: body.message },
    ];

    try {
      const response = await this.llmService.generateCompletion(messages, {
        temperature: 0.7,
        maxTokens: 1000,
      });

      return {
        success: true,
        data: {
          response: response.content,
          provider: response.provider,
          usage: response.usage,
        },
      };
    } catch (error) {
      return {
        success: false,
        message: '응답 생성 중 오류가 발생했습니다.',
        error: error.message,
      };
    }
  }
}

서비스 생성 자동화

여러 서비스를 생성하면서 반복 작업이 늘어나자, 자동화 스크립트를 만들었다:

// tools/scripts/create-service.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

function createService(serviceName) {
  console.log(`Creating service: ${serviceName}`);

  // Nx 애플리케이션 생성
  execSync(`npx nx g @nx/nest:app ${serviceName} --directory=apps/services`, 
    { stdio: 'inherit' });

  // E2E 테스트 애플리케이션 생성  
  execSync(`npx nx g @nx/nest:app ${serviceName}-e2e --directory=apps/services`, 
    { stdio: 'inherit' });

  // 프로젝트 설정 업데이트
  updateProjectConfig(serviceName);

  // 기본 템플릿 적용
  applyTemplate(serviceName);

  console.log(`Service ${serviceName} created successfully!`);
  console.log(`To start the service: nx serve ${serviceName}`);
  console.log(`To build the service: nx build ${serviceName}`);
  console.log(`To run tests: nx test ${serviceName}`);
}

function updateProjectConfig(serviceName) {
  const projectPath = `apps/services/${serviceName}/project.json`;
  const config = JSON.parse(fs.readFileSync(projectPath, 'utf8'));

  // 추가 태그 설정
  config.tags = [...(config.tags || []), 'scope:services', 'type:app'];

  // 환경 변수 설정
  config.targets.serve.options.envFile = '.env.local';

  fs.writeFileSync(projectPath, JSON.stringify(config, null, 2));
}

이 스크립트를 통해 새로운 서비스를 5분 안에 생성하고 바로 개발을 시작할 수 있었다.

4장: 개발 과정에서의 도전과 해결

타입 시스템과의 싸움

TypeScript 설정을 맞추는 과정에서 여러 문제에 부딪혔다. 특히 모노레포 환경에서 라이브러리 간 타입 참조가 제대로 작동하지 않는 문제가 있었다.

// tsconfig.base.json
{
  "compileOnSave": false,
  "compilerOptions": {
    "rootDir": ".",
    "sourceMap": true,
    "declaration": false,
    "moduleResolution": "node",
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "target": "es2015",
    "module": "esnext",
    "lib": ["es2020", "dom"],
    "skipLibCheck": true,
    "skipDefaultLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@ai-solution/core/auth": ["libs/core/auth/src/index.ts"],
      "@ai-solution/core/database": ["libs/core/database/src/index.ts"],
      "@ai-solution/core/llm": ["libs/core/llm/src/index.ts"]
    }
  },
  "exclude": ["node_modules", "tmp"]
}

경로 매핑을 통해 절대 경로 import를 가능하게 했지만, 빌드 시점에서 문제가 발생했다. 이를 해결하기 위해 각 라이브러리의 tsconfig.lib.json을 세심하게 조정했다:

// libs/core/auth/tsconfig.lib.json
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "module": "commonjs",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "declaration": true,
    "outDir": "../../../dist/libs/core/auth"
  },
  "include": ["src/**/*"],
  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
}

빌드 의존성 관리

모노레포의 장점이자 단점은 의존성 관리였다. core-auth가 변경되면 이를 사용하는 모든 서비스가 재빌드되어야 했다. Nx의 의존성 그래프를 활용하여 이를 최적화했다:

# 의존성 그래프 시각화
nx graph

# 영향받는 프로젝트만 빌드
nx affected:build --base=main --head=HEAD

# 특정 라이브러리 변경 시 영향 분석
nx affected:graph --base=main

환경 변수 관리의 복잡성

여러 서비스가 서로 다른 환경 변수를 필요로 하면서 관리가 복잡해졌다. 이를 해결하기 위해 계층적 환경 변수 구조를 도입했다:

# 프로젝트 루트
.env                    # 공통 환경 변수
.env.local             # 로컬 개발용 (gitignore)
.env.production        # 프로덕션용 (gitignore)

# 서비스별 환경 변수
apps/services/chat-service/.env
apps/services/analytics-service/.env

// apps/services/chat-service/src/main.ts
import { ConfigService } from '@nestjs/config';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get(ConfigService);

  // 환경별 설정
  const port = configService.get<number>('PORT', 3000);
  const environment = configService.get<string>('NODE_ENV', 'development');

  if (environment === 'production') {
    app.enableCors({
      origin: configService.get<string>('ALLOWED_ORIGINS', '').split(','),
      credentials: true,
    });
  } else {
    app.enableCors();
  }

  await app.listen(port);
  console.log(`Application is running on: ${await app.getUrl()}`);
}

5장: 성능 최적화와 모니터링

빌드 시간 최적화

초기에는 전체 프로젝트를 빌드하는데 5분 이상이 걸렸다. 이는 개발 생산성에 심각한 영향을 미쳤다. Nx의 캐싱 시스템을 활용하여 이를 개선했다:

// nx.json - 캐싱 설정
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "@nx/workspace/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test", "e2e"],
        "parallel": 3,
        "useDaemonProcess": true
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    }
  }
}

결과적으로 증분 빌드 시간을 30초 이내로 단축시킬 수 있었다.

메모리 사용량 모니터링

대용량 AI 모델을 다루면서 메모리 사용량이 중요한 이슈가 되었다. 각 서비스별로 메모리 모니터링을 구현했다:

// 메모리 사용량 모니터링 미들웨어
@Injectable()
export class MemoryMonitoringMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const memoryUsage = process.memoryUsage();
    const memoryInMB = {
      rss: Math.round(memoryUsage.rss / 1024 / 1024),
      heapTotal: Math.round(memoryUsage.heapTotal / 1024 / 1024),
      heapUsed: Math.round(memoryUsage.heapUsed / 1024 / 1024),
      external: Math.round(memoryUsage.external / 1024 / 1024),
    };

    if (memoryInMB.heapUsed > 512) { // 512MB 임계치
      console.warn(`High memory usage detected: ${JSON.stringify(memoryInMB)}`);
    }

    res.setHeader('X-Memory-Usage', JSON.stringify(memoryInMB));
    next();
  }
}

6장: 문서화와 개발 경험

API 문서화의 중요성

팀 규모가 커지면서 API 문서화의 중요성을 절감했다. Swagger를 도입하여 자동화된 API 문서를 구축했다:

// main.ts에서 Swagger 설정
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('AI Solution Center API')
    .setDescription('AI 솔루션센터 통합 API 문서')
    .setVersion('1.0')
    .addBearerAuth()
    .addTag('auth', '인증 관련 API')
    .addTag('chat', '채팅 관련 API')
    .addTag('analytics', '분석 관련 API')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}

// DTO에 Swagger 데코레이터 적용
export class ChatMessageDto {
  @ApiProperty({
    description: '사용자 메시지',
    example: '안녕하세요, AI 어시스턴트입니다.',
  })
  @IsString()
  @IsNotEmpty()
  message: string;

  @ApiProperty({
    description: '대화 ID (선택사항)',
    example: 'conv_123456789',
    required: false,
  })
  @IsOptional()
  @IsString()
  conversationId?: string;
}

개발자 경험 개선

개발자 경험을 개선하기 위해 여러 도구를 도입했다:

1. 코드 품질 도구

// .eslintrc.json
{
  "extends": ["@nx/eslint-plugin-nx/typescript"],
  "rules": {
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "prefer-const": "error"
  }
}

2. 프리커밋 훅

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

3. 커밋 메시지 규칙

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']
    ],
    'subject-max-length': [2, 'always', 100],
  },
};

7장: 배포와 운영

컨테이너화 전략

각 서비스를 독립적으로 배포하기 위해 Docker를 활용했다:

# apps/services/chat-service/Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
COPY yarn.lock ./
RUN yarn install --frozen-lockfile

COPY . .
RUN yarn nx build chat-service --prod

FROM node:18-alpine AS runner

WORKDIR /app
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nestjs -u 1001

COPY --from=builder /app/dist/apps/services/chat-service ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

USER nestjs
EXPOSE 3000

CMD ["node", "main.js"]

CI/CD 파이프라인

GitHub Actions을 사용하여 자동화된 배포 파이프라인을 구축했다:

# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Run affected tests
        run: yarn nx affected:test --base=origin/main

      - name: Run affected lint
        run: yarn nx affected:lint --base=origin/main

      - name: Run affected build
        run: yarn nx affected:build --base=origin/main

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to staging
        run: |
          # 스테이징 환경 배포 스크립트
          ./scripts/deploy-staging.sh

8장: 성과와 교훈

정량적 성과

6개월간의 개발 과정에서 다음과 같은 성과를 달성했다:

프로젝트 메트릭스:
├── 서비스 수: 7개
├── 코어 라이브러리: 3개
├── 코드 재사용률: 73%
├── 빌드 시간 단축: 70%
├── 버그 감소율: 45%
└── 개발 생산성 향상: 60%

기술적 성과

모듈화와 재사용성

// 코드 재사용 예시
// 모든 서비스에서 동일한 인증 로직 사용
@UseGuards(JwtAuthGuard)
@Get('protected')
protectedEndpoint(@CurrentUser() user: User) {
  return { user };
}

// 모든 엔티티에서 동일한 기본 필드 사용
@Entity()
export class CustomEntity extends BaseEntity {
  // 추가 필드만 정의
}

개발 속도 향상

# 새 서비스 생성: 5분
npm run create-service new-service

# 기능 추가: 기존 대비 50% 시간 단축
# 배포: 자동화로 95% 시간 단축

아키텍처적 통찰

이 프로젝트를 통해 얻은 가장 중요한 통찰은 "복잡성은 관리되어야 한다"는 것이었다.

복잡성 관리 전략:
├── 계층화: 비즈니스 로직과 인프라 분리
├── 추상화: 공통 기능의 라이브러리화
├── 표준화: 코딩 스타일과 패턴 통일
├── 자동화: 반복 작업의 스크립트화
└── 문서화: 지식의 체계적 관리

처음에는 모든 것을 한 번에 완벽하게 만들려고 했지만, 점진적 개선이 더 효과적임을 깨달았다. 특히 코어 라이브러리는 실제 사용 사례가 누적된 후에 안정화되었다.

팀워크와 협업

혼자 시작한 프로젝트였지만, 점차 팀이 확장되면서 협업의 중요성을 체감했다. 특히 다음 요소들이 핵심이었다:

1. 코드 리뷰 문화

// 리뷰 가이드라인
// 1. 비즈니스 로직이 명확한가?
// 2. 에러 처리가 적절한가?
// 3. 테스트 커버리지가 충분한가?
// 4. 성능상 이슈는 없는가?

2. 지식 공유
매주 금요일 기술 세션을 통해 새로운 기술이나 문제 해결 과정을 공유했다.

3. 페어 프로그래밍
복잡한 문제는 페어 프로그래밍을 통해 해결했고, 이는 코드 품질 향상에 큰 도움이 되었다.

에필로그: 미래를 향한 설계

현재 구축한 플랫폼은 시작점일 뿐이다. 앞으로 마이크로서비스 아키텍처로의 전환, 쿠버네티스 기반 오케스트레이션, 이벤트 기반 아키텍처 도입 등을 고려하고 있다.

미래 로드맵:
├── Q1: 마이크로서비스 전환 준비
│   ├── 서비스 메시 도입 (Istio)
│   ├── 분산 트레이싱 (Jaeger)
│   └── 중앙집중식 로깅 (ELK Stack)
├── Q2: 클라우드 네이티브 전환
│   ├── Kubernetes 클러스터 구축
│   ├── GitOps 파이프라인 (ArgoCD)
│   └── 인프라스트럭처 as 코드 (Terraform)
├── Q3: AI/ML 파이프라인 강화
│   ├── MLOps 플랫폼 구축
│   ├── 모델 버저닝 시스템
│   └── A/B 테스트 프레임워크
└── Q4: 성능 및 확장성 최적화
    ├── 캐싱 전략 고도화 (Redis Cluster)
    ├── 데이터베이스 샤딩
    └── CDN 및 엣지 컴퓨팅

이 프로젝트를 통해 배운 가장 중요한 교훈은 기술은 수단이지 목적이 아니라는 것이다. 사용자의 문제를 해결하는 것이 우선이고, 기술적 선택은 그 목적을 달성하기 위한 최적의 방법이어야 한다.

AI혁신 솔루션센터는 이제 실제 사용자들에게 가치를 제공하는 플랫폼으로 성장하고 있다. 앞으로도 지속적인 개선과 혁신을 통해 더 나은 AI 솔루션을 제공할 것이다.

*"좋은 아키텍처는 하루 아침에 만들어지지 않는다. 지속적인 개선과 학습을 통해 진화하는 것이다."*

Unitree SDK 분석해보기

글쓰는 연구원 상티 — Mon, 30 Jun 2025 17:21:16 +0900

개요

로보틱스 연구를 하다보면 특정 디바이스에 종속된 movement, locomotion, task를 수행해야 할 때가 있다. 최근들어 Unitree사의 Go2를 시뮬레이션상에서 연구 할 일이 많아 따로 작성해봄.

Unitree SDK2 Python은 Unitree 로봇(Go2, B2, G1, H1 등)을 제어하기 위한 공식 Python API임. 이 글은 Go2 로봇의 보행 로직을 중심으로 API의 작동 원리와 구현 방식을 분석해봄.

주요 특징

DDS(Data Distribution Service) 기반 통신: 실시간 분산 통신 프로토콜 사용
계층적 제어 구조: High-level(Sport Mode)과 Low-level 제어 분리
RPC 기반 서비스 아키텍처: 모듈화된 서비스 구조

시스템 아키텍처

1. 디렉토리 구조

unitree_sdk2_python/
├── example/              # 예제 코드
│   └── go2/
│       ├── high_level/   # 고수준 제어 예제
│       └── low_level/    # 저수준 제어 예제
├── unitree_sdk2py/       # 핵심 라이브러리
│   ├── core/            # 통신 채널 및 설정
│   ├── go2/             # Go2 전용 모듈
│   │   ├── sport/       # Sport 모드 제어
│   │   └── robot_state/ # 로봇 상태 관리
│   ├── rpc/             # RPC 통신 모듈
│   └── idl/             # 데이터 타입 정의

2. 통신 아키텍처

┌─────────────────┐     RPC/DDS     ┌─────────────────┐
│  Python Client  │ ◄─────────────► │  Robot Service  │
│  (SDK)          │                  │  (내장 서비스)   │
└─────────────────┘                  └─────────────────┘
        │                                     │
        │                                     │
    ┌───▼───┐                           ┌────▼────┐
    │  High │                           │  Low    │
    │  Level│                           │  Level  │
    └───────┘                           └─────────┘

보행 제어 방식

1. High-Level 제어 (Sport Mode)

고수준 제어는 SportClient를 통해 이루어지며, 복잡한 동작을 간단한 명령으로 실행할 수 있습니다.

주요 특징:

추상화된 명령: Move(vx, vy, vyaw) 같은 직관적인 인터페이스
자동 균형 제어: 내부적으로 자세 제어 및 균형 유지
사전 정의된 동작: 백플립, 춤, 계단 오르기 등

2. Low-Level 제어

저수준 제어는 개별 모터를 직접 제어하며, 정밀한 움직임 구현이 가능합니다.

주요 특징:

모터 직접 제어: 위치(q), 속도(dq), 토크(tau) 제어
PD 제어기: Kp(비례 게인), Kd(미분 게인) 설정
실시간 피드백: 2ms 주기로 제어 명령 전송

핵심 API 분석

1. SportClient 클래스 구조

class SportClient(Client):
    def __init__(self, enableLease: bool = False):
        super().__init__(SPORT_SERVICE_NAME, enableLease)

    def Init(self):
        # API 버전 설정
        self._SetApiVerson(SPORT_API_VERSION)

        # API 등록 (40개 이상의 API)
        self._RegistApi(SPORT_API_ID_DAMP, 0)
        self._RegistApi(SPORT_API_ID_MOVE, 0)
        # ...

2. 주요 보행 관련 메서드

기본 이동 제어

def Move(self, vx: float, vy: float, vyaw: float):
    """
    로봇 이동 제어
    - vx: 전진/후진 속도 (m/s)
    - vy: 좌우 이동 속도 (m/s)
    - vyaw: 회전 속도 (rad/s)
    """
    p = {"x": vx, "y": vy, "z": vyaw}
    parameter = json.dumps(p)
    code = self._CallNoReply(SPORT_API_ID_MOVE, parameter)
    return code

보행 모드 전환

def SwitchGait(self, t: int):
    """
    보행 패턴 변경
    - 0: 트로팅(Trotting) - 대각선 다리 동시 이동
    - 1: 기타 보행 패턴
    """
    p = {"data": t}
    parameter = json.dumps(p)
    code, data = self._Call(SPORT_API_ID_SWITCHGAIT, parameter)
    return code

고급 보행 기능

# 자유 보행 모드
def FreeWalk(self, flag: bool)

# 장애물 회피 보행
def FreeAvoid(self, flag: bool)

# 계단 오르기
def WalkStair(self, flag: bool)

# 직립 보행
def WalkUpright(self, flag: bool)

3. Low-Level 모터 제어

class MotorCmd_:
    mode: uint8      # 제어 모드 (0x01: PMSM 모드)
    q: float32       # 목표 위치 (라디안)
    dq: float32      # 목표 속도 (라디안/초)
    tau: float32     # 목표 토크 (Nm)
    kp: float32      # 위치 비례 게인
    kd: float32      # 속도 미분 게인

코드 실행 흐름

1. High-Level 보행 예제 실행 흐름

1. 초기화
   ├─ ChannelFactoryInitialize() - DDS 통신 채널 초기화
   ├─ SportClient 생성
   └─ client.Init() - API 등록

2. 명령 실행 루프
   ├─ 사용자 입력 대기
   ├─ 명령 선택 (예: Move, StandUp, BackFlip 등)
   ├─ RPC 호출 (_Call 또는 _CallNoReply)
   └─ 로봇 서비스에서 명령 실행

3. 내부 처리 과정
   ├─ JSON 파라미터 생성
   ├─ API ID와 함께 서비스 호출
   ├─ 서비스에서 명령 해석
   └─ 모터 제어 신호 생성 및 전송

2. Low-Level 제어 실행 흐름

1. 초기화
   ├─ 통신 채널 설정
   ├─ Publisher/Subscriber 생성
   └─ 초기 모터 위치 읽기

2. 제어 루프 (2ms 주기)
   ├─ 현재 상태 읽기 (LowState)
   ├─ 목표 위치 계산
   ├─ PD 제어기 파라미터 설정
   ├─ CRC 계산
   └─ 명령 전송 (LowCmd)

3. 보간 및 전환
   ├─ 시작 위치에서 목표 위치로 부드러운 전환
   ├─ 각 단계별 진행률 계산 (percent_1, percent_2...)
   └─ 선형 보간을 통한 관절 각도 계산

주요 보행 기능

1. 기본 보행 패턴

기능	API	설명
전진/후진	Move(vx, 0, 0)	직선 이동
좌우 이동	Move(0, vy, 0)	측면 이동 (크랩 워크)
제자리 회전	Move(0, 0, vyaw)	Yaw 축 회전
트로팅	SwitchGait(0)	대각선 다리 동시 이동

2. 고급 보행 기능

기능	API	설명
자유 보행	FreeWalk()	AI 기반 적응형 보행
장애물 회피	FreeAvoid()	센서 기반 자동 회피
계단 오르기	WalkStair()	계단 감지 및 적응
직립 보행	WalkUpright()	두 다리로 걷기
교차 보행	CrossStep()	다리 교차 패턴

3. 특수 동작

동작	API	설명
백플립	BackFlip()	후방 공중제비
좌측 플립	LeftFlip()	측면 공중제비
춤	Dance1(), Dance2()	사전 정의된 춤 동작
점프	FreeJump()	자유 점프 동작

결론 및 시사점

1. 강화학습 적용을 위한 고려사항

장점:

High-Level API: 복잡한 동작을 간단히 실행 가능
Low-Level 접근: 정밀한 모터 제어로 커스텀 보행 패턴 구현 가능
실시간 피드백: 2ms 주기의 빠른 제어 루프

도전 과제:

제한된 중간 수준 제어: High-Level과 Low-Level 사이의 갭
내부 알고리즘 불투명성: Sport 모드의 내부 구현 비공개
센서 데이터 접근: IMU, 발 힘 센서 등의 제한적 접근

2. 권장 접근 방법

초기 단계: High-Level API로 기본 동작 학습
중급 단계: TrajectoryFollow API로 경로 기반 보행 구현
고급 단계: Low-Level 제어로 커스텀 보행 패턴 개발

3. 주요 인사이트

계층적 제어의 중요성: 추상화 수준에 따른 적절한 API 선택
실시간성 보장: DDS 통신으로 낮은 지연시간 달성
모듈화된 구조: 각 기능이 독립적인 서비스로 구현

[부담없는 강화학습 이론]: On-Policy, Off-Policy

글쓰는 연구원 상티 — Fri, 20 Jun 2025 16:53:12 +0900

1. 핵심 개념 정립

1.1 Policy의 본질적 이해

Policy π(a|s): 상태 s에서 행동 a를 선택할 확률분포임
요리사가 재료(상태)를 보고 어떤 요리법(행동)을 쓸지 결정하는 확률적 판단 기준임
수학적으로 π: S → P(A)의 매핑 함수임

1.2 On-Policy vs Off-Policy의 철학적 차이

On-Policy: "배우는 정책 = 행동하는 정책"

현재 학습 중인 정책으로 직접 경험을 수집하고 그 경험으로만 학습함
학생이 자신의 공부법으로만 공부하고 그 결과로만 공부법을 개선하는 방식임

Off-Policy: "배우는 정책 ≠ 행동하는 정책"

다른 정책(behavior policy)으로 수집한 경험으로 목표 정책(target policy)을 학습함
다른 학생들의 공부 경험을 관찰하며 자신만의 최적 공부법을 찾는 방식임

2. On-Policy 방법론 심화 분석

2.1 SARSA (State-Action-Reward-State-Action)

핵심 업데이트 공식:

Q(s,a) ← Q(s,a) + α[r + γQ(s',a') - Q(s,a)]

수식 해부:

Q(s,a): 현재 상태-행동 가치 추정치
α: 학습률 (새로운 정보를 얼마나 반영할지)
r: 즉시 보상
γ: 할인 인자 (미래 보상의 중요도)
Q(s',a'): 다음 상태에서 실제로 취할 행동의 가치

직관적 이해:

예측 오차 [r + γQ(s',a') - Q(s,a)]를 계산함
실제 경험한 보상과 기대했던 가치의 차이를 학습에 반영함
보수적 운전자가 실제 경험한 길만으로 내비게이션을 업데이트하는 방식임

2.2 Policy Gradient 방법

기본 목적함수:

J(θ) = E_π[R_t] = Σ_s d^π(s) Σ_a π(a|s,θ) R^π(s,a)

정책 경사 정리 (Policy Gradient Theorem):

∇_θ J(θ) = E_π[∇_θ log π(a|s,θ) Q^π(s,a)]

수식 분해:

d^π(s): 정책 π 하에서의 상태 분포 (얼마나 자주 그 상태에 있는가)
∇_θ log π(a|s,θ): 정책의 로그 확률에 대한 경사 (어떤 방향으로 정책을 바꿀지)
Q^π(s,a): 현재 정책 하에서의 행동 가치 (그 행동이 얼마나 좋은지)

직관적 해석:

좋은 결과를 낸 행동의 확률은 높이고, 나쁜 결과를 낸 행동의 확률은 낮춤
화가가 성공한 그림 기법은 더 자주 쓰고, 실패한 기법은 덜 쓰는 학습 과정임

2.3 REINFORCE 알고리즘

업데이트 공식:

θ ← θ + α ∇_θ log π(a_t|s_t,θ) G_t

여기서 G_t = Σ_{k=0}^{T-t-1} γ^k r_{t+k+1}

핵심 아이디어:

에피소드가 끝난 후 전체 수익 G_t를 계산함
좋은 에피소드에서 한 행동들의 확률을 증가시킴
몬테카를로 방식으로 분산이 큼 (운의 영향이 큼)

3. Off-Policy 방법론 심화 분석

3.1 Q-Learning의 수학적 구조

벨만 최적 방정식:

Q*(s,a) = E[r + γ max_a' Q*(s',a') | s,a]

Q-Learning 업데이트:

Q(s,a) ← Q(s,a) + α[r + γ max_a' Q(s',a') - Q(s,a)]

On-Policy와의 핵심 차이:

SARSA: Q(s',a') (실제로 할 행동)
Q-Learning: max_a' Q(s',a') (최적 행동)

직관적 비유:

SARSA: 실제 운전 경험으로만 길을 배움
Q-Learning: 모든 가능한 길을 비교해서 최고의 길을 찾음

3.2 Importance Sampling의 수학적 기초

문제 정의:
목표 정책 π로 기댓값을 구하고 싶지만 행동 정책 b로 데이터를 수집함

Importance Sampling 공식:

E_π[f(X)] = E_b[f(X) * π(X)/b(X)]

강화학습 적용:

E_π[G_t] = E_b[G_t * Π_{k=t}^{T-1} π(a_k|s_k)/b(a_k|s_k)]

직관적 해석:

다른 사람의 경험을 내 상황에 맞게 가중치를 조정해서 활용함
음식 리뷰를 볼 때 나와 취향이 비슷한 사람의 리뷰에 더 가중치를 두는 방식임

3.3 Off-Policy Actor-Critic

이중 네트워크 구조:

Actor: π_θ(a|s) (정책 네트워크)
Critic: V_φ(s) 또는 Q_φ(s,a) (가치 네트워크)

업데이트 공식:

θ ← θ + α_θ ∇_θ log π_θ(a|s) [Q_φ(s,a) - V_φ(s)]
φ ← φ + α_φ ∇_φ [Q_φ(s,a) - V_φ(s)]²

핵심 아이디어:

Actor는 정책을 개선하고 Critic은 가치를 평가함
감독(Critic)이 배우(Actor)의 연기를 평가하며 함께 발전하는 구조임

4. 수렴성과 안정성 분석

4.1 On-Policy의 수렴 조건

Robbins-Monro 조건:

Σ_t α_t = ∞, Σ_t α_t² < ∞

의미:

학습률이 충분히 크게 누적되어야 함 (탐험 충분)
학습률 제곱의 합은 유한해야 함 (수렴 보장)
대표적 예: α_t = 1/t

4.2 Off-Policy의 수렴 조건

Deadly Triad 문제:

Function Approximation (함수 근사)
Bootstrapping (부트스트래핑)
Off-Policy Learning

수렴 어려움의 원인:

분포 변화로 인한 불안정성
Importance Sampling의 높은 분산
Target Network 없이는 발산 가능성 높음

5. 실제 적용 시 고려사항

5.1 탐험-활용 딜레마

ε-greedy 정책:

π(a|s) = {
  1-ε+ε/|A|  if a = argmax Q(s,a)
  ε/|A|      otherwise
}

UCB (Upper Confidence Bound):

a_t = argmax_a [Q_t(a) + c√(ln t / N_t(a))]

5.2 Experience Replay의 수학적 근거

배치 업데이트:

L(θ) = E_{(s,a,r,s')~D}[(r + γ max_a' Q(s',a';θ^-) - Q(s,a;θ))²]

장점:

데이터 효율성 증대
상관관계 제거로 안정성 향상
Off-Policy 학습 가능

6. 결론 및 선택 가이드

6.1 On-Policy 선택 기준

안정적 수렴이 중요한 경우
연속적 제어 문제
정책 자체가 중요한 경우

6.2 Off-Policy 선택 기준

데이터 효율성이 중요한 경우
과거 경험 재활용이 필요한 경우
탐험 데이터가 제한적인 경우

핵심 메시지:
On-Policy는 안전한 보수적 학습, Off-Policy는 효율적이지만 불안정할 수 있는 학습임. 문제 특성에 따라 적절한 방법론을 선택하는 것이 핵심임.

Quadruped Robot Simulation Based Reinforcement Training 연구노트 (1)

글쓰는 연구원 상티 — Fri, 20 Jun 2025 16:41:06 +0900

필수 사전지식

1. PPO, SAC, TD3 등 연속 제어 알고리즘

1.1 PPO (Proximal Policy Optimization)

PPO는 정책 최적화 알고리즘 중 가장 널리 사용되는 알고리즘임. 기존 TRPO의 복잡한 제약 조건을 단순화하여 구현이 용이하면서도 안정적인 학습이 가능함.

PPO의 핵심 개념: 정책 업데이트 시 이전 정책과 너무 많이 달라지지 않도록 제한하는 것임. 이를 통해 학습의 안정성을 확보함.

Clip 함수의 역할: PPO는 확률 비율을 클리핑하여 정책 업데이트의 크기를 제한함. 클리핑 범위는 일반적으로 [1-ε, 1+ε]로 설정하며, ε는 0.1~0.3 범위에서 설정함.

사족보행에서의 장점: PPO는 연속적인 관절 제어에 적합하며, 복잡한 보상 구조에서도 안정적으로 학습이 가능함. 또한 병렬 환경에서의 데이터 수집에 효율적임.

1.2 SAC (Soft Actor-Critic)

SAC는 엔트로피 정규화를 통해 탐험과 활용의 균형을 자동으로 조절하는 off-policy 알고리즘임. 최대 엔트로피 강화학습의 원리를 따름.

엔트로피 정규화: 정책의 엔트로피를 목적함수에 추가하여 탐험을 장려함. 이를 통해 지역 최적점에 빠지는 것을 방지하고 더 robust한 정책을 학습함.

자동 온도 조절: SAC는 온도 파라미터 α를 자동으로 조절하여 탐험의 정도를 동적으로 결정함. 이는 수동 하이퍼파라미터 튜닝의 부담을 줄여줌.

샘플 효율성: Off-policy 특성으로 인해 경험 재생을 활용할 수 있어 샘플 효율성이 높음. 사족보행과 같이 물리 시뮬레이션 비용이 높은 환경에서 유리함.

1.3 TD3 (Twin Delayed Deep Deterministic Policy Gradient)

TD3는 DDPG의 개선된 버전으로, 세 가지 주요 기법을 통해 성능을 향상시킨 알고리즘임.

Twin Critics: 두 개의 Q-함수를 사용하여 overestimation bias를 줄임. 두 Q-함수 중 작은 값을 사용하여 보수적인 추정을 수행함.

Delayed Policy Updates: 정책 업데이트를 비평자 업데이트보다 적게 수행하여 정책이 불안정한 가치 함수에 의해 오도되는 것을 방지함.

Target Policy Smoothing: 타겟 정책에 노이즈를 추가하여 함수 근사 오차에 대한 robustness를 증가시킨 것임.

2. Actor-Critic 구조와 정책 경사법

2.1 Actor-Critic 구조

Actor-Critic은 정책 기반 방법과 가치 기반 방법의 장점을 결합한 구조임. Actor는 정책을 학습하고, Critic은 가치 함수를 학습함.

Actor의 역할: 주어진 상태에서 어떤 행동을 취할지 결정하는 정책 π(a|s)를 학습함. 사족보행에서는 각 관절의 토크나 목표 각도를 출력함.

Critic의 역할: 상태의 가치 V(s) 또는 상태-행동 쌍의 가치 Q(s,a)를 추정함. 이는 Actor의 정책 개선에 필요한 피드백을 제공함.

상호작용: Critic이 제공하는 가치 추정을 통해 Actor는 더 나은 행동을 학습하고, Actor의 행동을 통해 Critic은 더 정확한 가치 함수를 학습함.

2.2 정책 경사법 (Policy Gradient)

정책 경사법은 정책을 직접 최적화하는 방법으로, 정책 파라미터에 대한 기댓값의 gradient를 계산하여 정책을 개선함.

REINFORCE 알고리즘: 가장 기본적인 정책 경사법으로, 몬테카르로 방법을 사용하여 정책 gradient를 추정함. 하지만 높은 분산으로 인해 학습이 불안정함.

Baseline의 도입: 분산을 줄이기 위해 baseline (일반적으로 가치 함수)을 사용함. 이를 통해 advantage 함수 A(s,a) = Q(s,a) - V(s)를 계산함.

자연 정책 경사법: 정책 공간의 기하학적 구조를 고려하여 더 효율적인 업데이트를 수행하는 방법임. Fisher 정보 행렬을 사용하여 자연 gradient를 계산함.

3. 경험 재생과 샘플 효율성

3.1 경험 재생 (Experience Replay)

경험 재생은 과거의 경험을 저장했다가 재사용하는 기법으로, off-policy 알고리즘에서 핵심적인 역할을 함.

리플레이 버퍼: 경험 (s, a, r, s')을 저장하는 메모리 구조임. 일반적으로 FIFO 방식으로 관리되며, 최대 크기에 도달하면 오래된 경험을 제거함.

샘플링 전략: 균등 샘플링이 기본이지만, Prioritized Experience Replay처럼 중요도에 따른 샘플링도 사용됨. TD-error가 큰 경험을 더 자주 샘플링함.

데이터 상관관계 해결: 연속적인 경험 간의 상관관계를 줄여 학습의 안정성을 향상시킴. 이는 신경망 학습에서 중요한 i.i.d 가정을 만족하게 도움.

3.2 샘플 효율성

샘플 효율성은 주어진 수의 환경 상호작용으로 얼마나 좋은 성능에 도달할 수 있는지를 나타내는 지표임.

On-policy vs Off-policy: Off-policy 방법이 일반적으로 샘플 효율성이 높음. 과거 데이터를 재사용할 수 있기 때문임.

함수 근사의 영향: 신경망과 같은 함수 근사기의 사용은 일반화 능력을 높여 샘플 효율성을 개선함.

탐험 전략: 효율적인 탐험 전략은 샘플 효율성에 직접적인 영향을 미침. UCB, Thompson Sampling 등의 방법이 사용됨.

4. 보상 함수 설계 및 희소 보상 문제

4.1 보상 함수 설계 원칙

보상 함수는 에이전트가 학습해야 할 목표를 수치적으로 표현하는 핵심 요소임. 잘못 설계된 보상 함수는 의도하지 않은 행동을 유발할 수 있음.

명확성: 보상 함수는 원하는 행동을 명확하게 반영해야 함. 모호한 보상은 바람직하지 않은 행동을 학습시킬 수 있음.

균형성: 여러 목표 간의 균형을 맞춰야 함. 사족보행에서는 속도, 안정성, 에너지 효율성 등을 모두 고려해야 함.

Shaping: 중간 목표를 통해 학습을 가이드하는 기법임. 하지만 과도한 shaping은 local optima에 빠뜨릴 수 있음.

4.2 사족보행을 위한 보상 함수 설계

전진 보상: 로봇의 전진 속도에 비례하는 보상을 제공함. 일반적으로 목표 속도와의 차이에 반비례하도록 설계함.

안정성 보상: 몸체의 방향, 높이, 각속도 등을 통해 안정성을 평가함. 급격한 움직임이나 넘어짐에 대해 페널티를 부여함.

에너지 효율성: 관절 토크의 제곱합이나 전력 소모를 최소화하도록 하는 보상을 추가함.

접촉 패턴: 적절한 발걸음 패턴을 유도하기 위해 발과 지면의 접촉 시간과 패턴을 고려함.

4.3 희소 보상 문제 해결

희소 보상 환경에서는 보상 신호가 드물게 발생하여 학습이 어려움. 이를 해결하기 위한 다양한 방법이 개발됨.

커리큘럼 학습: 쉬운 과제부터 시작하여 점진적으로 난이도를 높이는 방법임. 사족보행에서는 평지 → 경사 → 계단 순으로 진행할 수 있음.

모방 학습: 전문가의 시연을 통해 초기 정책을 학습한 후 강화학습으로 개선하는 방법임. Behavioral Cloning이나 GAIL 같은 기법이 사용됨.

내재적 동기: 호기심이나 내재적 보상을 통해 탐험을 장려하는 방법임. Count-based exploration이나 ICM (Intrinsic Curiosity Module) 등이 있음.

HER (Hindsight Experience Replay): 실패한 경험도 다른 목표에 대해서는 성공으로 간주하여 학습에 활용하는 방법임.

5. 구현 시 고려사항

5.1 하이퍼파라미터 튜닝

학습률: 너무 높으면 불안정하고, 너무 낮으면 학습이 느림. 일반적으로 3e-4 ~ 1e-3 범위에서 시작함.

배치 크기: 메모리와 계산 효율성을 고려하여 결정함. 일반적으로 64 ~ 512 사이에서 설정함.

네트워크 구조: Hidden layer의 수와 크기를 결정함. 사족보행에서는 보통 2-3개의 hidden layer와 256-512개의 뉴런을 사용함.

5.2 안정성 확보

Gradient Clipping: 기울기 폭발을 방지하기 위해 기울기의 norm을 제한함.

Target Network: Q-learning에서 학습의 안정성을 위해 천천히 업데이트되는 타겟 네트워크를 사용함.

정규화: 입력 정규화와 가중치 정규화를 통해 학습의 안정성을 향상시킴.

이러한 강화학습 기초 지식들을 바탕으로 Unitree Go2의 사족보행 제어를 위한 효과적인 강화학습 시스템을 구축할 수 있음. 각 알고리즘의 특성을 이해하고 문제 상황에 맞는 적절한 선택과 조합이 성공의 핵심임.

상티 2024 회고 (늦었지만 전반기 회고임)

글쓰는 연구원 상티 — Thu, 31 Oct 2024 02:23:14 +0900

최근에 바빠서 죽는 줄 알았다.

대학원 진학으로 인해서 학술관련 행사 참여도 반강제 ( ???: 상현아 갔다 와야겠지 ? ) 스럽게 많이 다녔고 장기간의 외주용역 계약 체결 후 작업이나 소속이전으로 인한 인수인계 레퍼런스 정리들로 하루하루 타이트 하게 지낸 것 같다.

2024년의 전반기 나는 무엇을 해왔을까 되돌아보는 시간..

1. 초음파 연구실에서의 마무리

2023년부터 의용공학부 모 초음파 연구실에 합류했었다.

연구나 실험쪽에선 경험도 풍부하고 실력 좋은 대학원생분들이 많았지만 소속학과 자체가 코드구현이나 개발쪽에 특화되어있지 않다보니 연구 데이터나 설계는 이미 레디 되어있는 상태에서 해당 부분의 문제들을 해결하기 위해 합류한 느낌이 강했었다.

1-1: JVM 안하고 싶었다.

2023년엔 거의 대부분을 SpringBoot을 사용했었기에 JVM은 많이 질려있는 상태였다.

허나 초기에 가장 먼저 해결 할 과제가 Java 기반 안드로이드 초음파 신호처리 앱의 성능 향상이었기에 다시 한번 Java에 손을 대게 된다.

벌크 형태로 들어오는 초음파 raw Data를 실시간 프레임 단위로 시각화 하는 프로젝트였는데, 이미 레거시로 일부 도메인 로직은 구현되어있었으나 렌더링을 하는 과정에서 성능저하들이 있었기에 몇차례 성능 개선을 통해서 버퍼링, 화질 개선을 진행했다.

사실 이제와서 보니까 뭘 했는지 가물가물 하다만 나름 재미있었던 순간이 많았다.

하지만 근본적인 문제는 JVM 기반 OpenCV의 성능 오버헤드, 성능저하였기에 간접적인 요행 (?) 으로는 해당 버퍼링을 해결할 수 없었고

최종적으로 중요 도메인 로직을 JNI를 사용한 C++ 기반 로직으로 변경해야한다는 암울한 결과를 내릴 수 밖에 없었는데...

딱봐도 알겠지마는 DX를 단 하나도 고려하지 않은 어마어마한 이식 난이도와 복잡함에 의욕을 상실해버렸고 또 다른 요행(바라지 말라며)을 찾아보았는데...

인새앵..

그러다가 Rust 만지게 됐습니다.

Rust기반 멀티플랫폼 개발기 (1)

갑자기 어떤 경위로.. 무슨 Rust를 만지느냐 필자는 보안을 갖다버린 후 Java, Python 이외에는 크게 언어를 만진적이 없다. 심지어 익스또한 파이썬으로 짜기 때문에 읽는 것을 제외하고 작성하는

sxngt.github.io

겟츠비 다루는게 좀 어리숙해서 썸네일이 이상하다마는 적다만 글이 있다. ( 블로그 난민 시절을 겪다보니 여기저기 흩어져있음)

GitHub - sxngt/MITS_Rust_Multiplatform_SDK: MITS Rust기반 다언어 지원 SDK 제너레이터

MITS Rust기반 다언어 지원 SDK 제너레이터. Contribute to sxngt/MITS_Rust_Multiplatform_SDK development by creating an account on GitHub.

github.com

러스트 로직을 쉘스크립트를 통해 쉽게 쉽게 이전할 수 있지만 사실 이것보다 중요했던건 인간 GC가 되어 신호처리 로직을 PORO (플레인 올드 러스트 옵젴... 사실 없는말임)으로 짜야 하는 점, 이후 중요한 Matrix 연산처리를 Rust-OpenCV로 처리하고 각 아키텍쳐에 맞게 빌드해야하는 삽질들이 더 힘들었지만 괜찮은 인프라 하나 남겨두고 갔다는 점이 보람찼다.

1-2. 딥러닝도 해야겠더라

대학원생인데 딥러닝 머신이 왔다면(1)

난 왜 이 글을 쓰고 있는가에 대하여 항상 느끼는건데 딥러닝 레퍼런스는 항상 부족하다. 보통 오류메세지에 대한 해결 방법이나 삽질기, TIL 뉘앙스에 스무뜨 하게 묻어나오는 그런 레퍼런스들

velog.io

역시 난민시절 흩어져있는 글 주서옴

무튼 딥러닝 연구도 해야하고, 해당장비도 온 상태에서 서버 형태로 굴리지 않으면 안되었기에 인프라 작업도 진행했었다.

나는 Vim충이라서 CLI말고 필요 없었다만 대의를 위한 code-server도 설치해보고, Conda 집어던지기와 동시에 pyenv로 쾌적한 환경 설계 등등 재밌는 경험은 많이 했다만 개발에 관련된 파트는 아니라서 넘어가겠다.

생각보다 code-server가 좋았는데, 그 만큼 아쉬운 경험들도 많았어서 추후 시간이 나면 fork 떠서 조금 더 성향에 맞게 다듬어보고싶다.

파이썬, 딥러닝 환경에 조금은 안맞는것들이 있었달까.

2. 재미있는 ( 하하 ) 보안 학술대회

부전공이 산업보안인데, 사실 다전공 학사였기에 골랐을 뿐 나의 부전공에 대하여 전혀 인식이 없었지만 졸업을 위해서라면 전공과목을 이수했어야 했고, 가장 간단하고 직관적으로 좋은 성적을 내기 위한 방법은 논문 제출 후 학술대회 수상.. 으로 A+과 맞교환 하는 교수님과의 어엄청난 딜이 있었다.

이전 직장에서 연구 개발했던 MPTCP 관련 주제로 논문을 작성할까 싶었지만 학사신분으로 나가는 학술대회이기도 했고 웹 / 클라우드 개발부문으로 접수했기에 너무 고전적인 보안보단 웹개발을 하는 과정에서 생길 수 있는 보안 허점에 대한 인식 개선을 주제로 라이트하게 작성했다.

근데 여기서 진짜 문제는 개최장소가 나주였다는 점

김해에서 나주... 김해에서 나주...

어메이징 ㅋㅋ

이런 낭만적인 여행 기회를 선사해주시는 하늘의 가르킴에 눈물이 나기도 전에 해당 루트는 새벽 5시 기상하여 첫차를 타도 발표시간 전에 도착하지 못하기 때문에 몹시 럭키비키한 마인드셋으로 이틀전부터 기차여행을 떠나버렸다.

생각해보니 딱히 혼자 여행이라던지 요양을 해본 적이 딱히 없었는데 막상 또 닥쳐서 해보니 나쁘지 않았던 것 같다.

잘 곳이 ? 필요하기도 했고 (사실 그게 전부다) 직장따라 사천으로 끌려간 선배도 오랜만에 보고싶었기에 바로 진주 - 사천으로 찍었다.

카이의 아들 김수성씨 특별출현

아쉽게도 평일 깜짝 습격이었기에 뭘 이렇다하게 함께하진 못했지만 잠깐 본 것 만으로 의미 깊었다. 기차여행 떠나니까 참 사소한것에도 의미가 깊어진것 같다.

캬 이게 진짜 내츄럴이지

목포도 함 찍어주고

게스트 하우스에서 잠도 자고

아무튼 나주행을 계기로 낭만있는 2박3일 기차여행을 마치고 나주에 도착해서 바로 프레젠테이션을 시작했다.

보면 알겠다시피 gRPC 기반으로 MSA 서버를 구축할때 정말 기본적인 설정값들로 통신하는형태의 구현형태 레퍼런스가 매우 많은 것 같아서 그런 형태로 진행했을시의 워스트 시나리오를 시현하고 최소한의 보안구현 요구스펙을 소개하는 PT를 가졌다.

실제로 개발하던 서비스의 비즈니스 로직을 가린 채 결제서버의 데이터 파이프라인이 갈취당했을 때의 시나리오를 설명하여 경각심을 강조했다.

물론 공모파트 자체가 웹개발 / 클라우드 였지만 대부분의 참가자와 심사위원분들이 보안전공이셨기에 최대한 서비스 개발단계에서의 기초적인 네트워크 커넥션에 대한 설명도 자세히 기제하여 진행했다.

TLS 암호화와 각 클라이언트 - 서버간의 더블체크에 대한 필요성을 강조하고 구현을 설명하며 끝난 발표..

발표 이후 생각보다 촘촘하고 거센 QnA에서 살짝 당황했지만 실제 개발하고 경험했던 시나리오를 기반으로 작성한 PT이다보니 임기응변에 꽤 능했던 것 같다.

아무튼 그렇게 수상엔딩

물론 이젠 많이 거리가 멀어진 보안과 다시 손잡아본 경험과 오랜만의 PT도 인상깊은 경험이었지만, 가장 좋았던 순간들과 경험들은 혼자 여러 곳을 돌아다니고 사색하며 얻은 내적 성숙함과 묵혀놨던 잡념을 꺼내어 모두 풀어놓을 수 있었던 "여행"이 가장 뜯깊었던 것 같다.

3. 재미있는 ( 하하 ) 넷제로 해커톤

이번엔 대학원 지도교수님께서 가볍게 ( 매우 무겁게 ) 제안해주신 덕에 SW융합대학 소속 대학생들을 대상으로 진행하는 넷제로 해커톤에 참여하게 되었다.

숙식 - 경비지원이 있었기에 가벼운 마음으로 갈 수 있었다.

경비지원이라는 말에 바로 양심탈거하고 비행기 타고 출발해버렸다. 약간의 골때리는 에피소드가 있었다 하면

수월한 개발을 위해서 챙겨간 나의 커스텀 키보드 가방이 마치 폭발물 처럼 보인 나머지 게이트에 들어가는 과정이 썩 매끄럽지만은 못했다는 점......

랜덤 팀 빌딩 이후 자연스럽게 팀장으로 떠밀려 (?) 진행하게 되어버린 아이디어 토론. 이후 바로 개발을 진행하게 된다.

지금부터 밤샘지옥 시작

환경수호가 개발주제였기 때문에 (자세히는 탄소중립) 우리팀은 "업사이클링 마일리지를 통한 구매유도 쇼핑몰"을 주제로 선정했다.

AWS에서 주관한 대회였기에 AWS의 각종 서비스가 개발과정에서 공짜였음으로 AWS Lambda, S3, RDS, EC2 등등 야무지게 써가면서 MSA환경을 구축했다.

각 쇼핑몰에서 업사이클링에 적합한 항목을 크롤링해서 DB에 적재하고 각 상품에 대한 업사이클링, 환경수호에 긍정적인 영향을 미치는 에코 지수를 LLM 기반 모델이 점수를 책정하여 추천항목에 올리는 형태의 마일리지 퀘스트형 쇼핑 앱을 완성했다.

팀장은.. 역시 발표를..

비교적 짧은 시간이었지만 기술적인 부분, 특히 아키텍쳐에서는 높은 완성도를 갖추기 위해 노력했다.

다만 아쉬운 점이 있었다면 너무 기술적인 부분에 초점을 두어 오버엔지니어링임을 간과했다는 점, 사실상 웹서비스 개발이 가능했던 팀원이 혼자였기에 기술적인 부분보단 단순한 구현으로 전환하여 더욱이 아이디어에 초점을 두었어야 했다는 점 등이 있었다.

그래도 좋았던 부분은 개발을 해보지 않은 24학번 팀원후배는 기획과 디자인에 열심히 기여할 수 있는 분위기를 만들어 주어서 팀의 응집도를 많이 늘렸고, 파이썬을 할 수 있었던 나머지 두 팀원들에게 크롤러 튜토리얼과 약간의 튜터링으로 크롤러 서버 개발의 중요 로직에 기여할 수 있도록 하여 모두가 프로덕트의 중요한 부분에 기여할 수 있도록 완급조절하여 모두가 성취감을 느낄 수 있었다는 점이었다.

이것도 결 국

수상엔딩

자세히 보다보면 내 뒷통수가 좀 보이지 않을까

4. 제법 큰 사이즈의 외주개발

5월 중순.. 본래는 사이드 프로젝트나 오픈소스 개발이 좀 하고 싶었어서 주변을 돌아보고 있던 시기였는데 운좋게도 좋은 조건에 외주개발을 할 수 있는 기회가 생겨 큰 프로덕트에 투입되었다.

적다보니 티스토리 에디터가 못버텨서 너무 버벅거리니 쫄림으로 2편에서 더 작성하겠다...

같이 연구해요

AI혁신 솔루션센터 개발 여정: 모노레포 아키텍처로 시작하는 엔터프라이즈 플랫폼 구축기

프롤로그: 예상치 못한 리더십의 시작

1장: 아키텍처의 선택 - 왜 모노레포인가?

문제 정의: 복잡성의 늪

모노레포 선택의 근거

Nx 선택의 기술적 배경

2장: 코어 라이브러리 설계 - 공통 기능의 추상화

아키텍처 설계 원칙

core-auth: 보안의 중심축

core-database: 데이터 접근의 표준화

core-llm: AI 기능의 통합

3장: 실제 서비스 구현 - 이론에서 실전으로

Chat Service: 실시간 대화의 구현

서비스 생성 자동화

4장: 개발 과정에서의 도전과 해결

타입 시스템과의 싸움

빌드 의존성 관리

환경 변수 관리의 복잡성

5장: 성능 최적화와 모니터링

빌드 시간 최적화

메모리 사용량 모니터링

6장: 문서화와 개발 경험

API 문서화의 중요성

개발자 경험 개선

7장: 배포와 운영

컨테이너화 전략

CI/CD 파이프라인

8장: 성과와 교훈

정량적 성과

기술적 성과

아키텍처적 통찰

팀워크와 협업

에필로그: 미래를 향한 설계

Unitree SDK 분석해보기

목차

개요

주요 특징

시스템 아키텍처

1. 디렉토리 구조

2. 통신 아키텍처

보행 제어 방식

1. High-Level 제어 (Sport Mode)

주요 특징:

2. Low-Level 제어

주요 특징:

핵심 API 분석

1. SportClient 클래스 구조

2. 주요 보행 관련 메서드

기본 이동 제어

보행 모드 전환

고급 보행 기능

3. Low-Level 모터 제어

코드 실행 흐름

1. High-Level 보행 예제 실행 흐름

2. Low-Level 제어 실행 흐름

주요 보행 기능

1. 기본 보행 패턴

2. 고급 보행 기능

3. 특수 동작

결론 및 시사점

1. 강화학습 적용을 위한 고려사항

장점:

도전 과제:

2. 권장 접근 방법

3. 주요 인사이트

[부담없는 강화학습 이론]: On-Policy, Off-Policy

1. 핵심 개념 정립

1.1 Policy의 본질적 이해

1.2 On-Policy vs Off-Policy의 철학적 차이

2. On-Policy 방법론 심화 분석

2.1 SARSA (State-Action-Reward-State-Action)

2.2 Policy Gradient 방법

2.3 REINFORCE 알고리즘

3. Off-Policy 방법론 심화 분석

3.1 Q-Learning의 수학적 구조

3.2 Importance Sampling의 수학적 기초

3.3 Off-Policy Actor-Critic

4. 수렴성과 안정성 분석

4.1 On-Policy의 수렴 조건