4장: GraphQL — 유연한 데이터 쿼리

# 1. 모델 정보 조회
GET /api/v1/models/claude-4
# 응답: 모델 전체 정보 (불필요한 필드 포함)
 
# 2. 모델의 가격 정보
GET /api/v1/models/claude-4/pricing
# 응답: 가격 전체 정보
 
# 3. 최근 사용 이력
GET /api/v1/models/claude-4/usage?limit=5
# 응답: 사용 이력 목록
 
# 총 3번의 HTTP 요청, 불필요한 데이터 포함

query GetModelDetails {
  model(id: "claude-4") {
    name
    provider
    contextWindow
    pricing {
      inputPerMillion
      outputPerMillion
      currency
    }
    recentUsage(limit: 5) {
      date
      totalTokens
      cost
    }
  }
}

# 스칼라 타입
scalar DateTime
scalar JSON
 
# 열거형
enum ModelProvider {
  OPENAI
  ANTHROPIC
  GOOGLE
  META
}
 
enum ModelCategory {
  CHAT
  EMBEDDING
  IMAGE
  AUDIO
  CODE
}
 
enum FinishReason {
  STOP
  LENGTH
  TOOL_CALLS
  CONTENT_FILTER
}
 
enum RunStatus {
  PENDING
  RUNNING
  COMPLETED
  FAILED
  CANCELLED
}
 
# 타입 정의
type Model {
  id: ID!
  name: String!
  provider: ModelProvider!
  category: ModelCategory!
  contextWindow: Int!
  maxOutputTokens: Int!
  pricing: ModelPricing!
  capabilities: [String!]!
  deprecated: Boolean!
  deprecationDate: DateTime
  createdAt: DateTime!
}
 
type ModelPricing {
  inputPerMillion: Float!
  outputPerMillion: Float!
  currency: String!
}
 
type Completion {
  id: ID!
  model: Model!
  choices: [Choice!]!
  usage: TokenUsage!
  finishReason: FinishReason!
  latencyMs: Int!
  createdAt: DateTime!
}
 
type Choice {
  index: Int!
  message: Message!
  finishReason: FinishReason!
}
 
type Message {
  role: String!
  content: String!
  toolCalls: [ToolCall!]
}
 
type ToolCall {
  id: String!
  name: String!
  arguments: JSON!
}
 
type TokenUsage {
  promptTokens: Int!
  completionTokens: Int!
  totalTokens: Int!
  estimatedCost: Float!
}
 
type UsageSummary {
  date: DateTime!
  model: String!
  totalRequests: Int!
  totalTokens: Int!
  totalCost: Float!
  averageLatencyMs: Float!
}
 
type Run {
  id: ID!
  status: RunStatus!
  model: Model!
  input: JSON!
  output: JSON
  usage: TokenUsage
  error: RunError
  createdAt: DateTime!
  completedAt: DateTime
}
 
type RunError {
  type: String!
  message: String!
  code: String
}
 
# 페이지네이션 (Relay 커넥션 스펙)
type ModelConnection {
  edges: [ModelEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type ModelEdge {
  node: Model!
  cursor: String!
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
type CompletionConnection {
  edges: [CompletionEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type CompletionEdge {
  node: Completion!
  cursor: String!
}
 
# 입력 타입
input CompletionInput {
  model: String!
  messages: [MessageInput!]!
  temperature: Float = 1.0
  maxTokens: Int
  tools: [ToolInput!]
}
 
input MessageInput {
  role: String!
  content: String!
}
 
input ToolInput {
  name: String!
  description: String!
  parameters: JSON!
}
 
input UsageFilterInput {
  startDate: DateTime!
  endDate: DateTime!
  models: [String!]
  providers: [ModelProvider!]
}
 
# 쿼리
type Query {
  # 모델 조회
  model(id: ID!): Model
  models(
    first: Int
    after: String
    provider: ModelProvider
    category: ModelCategory
  ): ModelConnection!
 
  # 실행 이력
  completion(id: ID!): Completion
  completions(
    first: Int
    after: String
    model: String
  ): CompletionConnection!
 
  # 비용 분석
  usageSummary(filter: UsageFilterInput!): [UsageSummary!]!
  
  # 실행 상태
  run(id: ID!): Run
}
 
# 뮤테이션
type Mutation {
  # 텍스트 완성 요청
  createCompletion(input: CompletionInput!): Completion!
  
  # 배치 작업
  createBatchRun(inputs: [CompletionInput!]!): [Run!]!
  cancelRun(id: ID!): Run!
}
 
# 구독 (실시간 업데이트)
type Subscription {
  # 실행 상태 변경 감지
  runStatusChanged(runId: ID!): Run!
  
  # 실시간 스트리밍 완성
  completionStream(input: CompletionInput!): StreamChunk!
}
 
type StreamChunk {
  delta: String!
  finishReason: FinishReason
  usage: TokenUsage
}

import { GraphQLResolveInfo } from "graphql";
import { DataSources } from "../datasources";
 
interface Context {
  dataSources: DataSources;
  userId: string;
}
 
export const modelResolvers = {
  Query: {
    model: async (
      _: unknown,
      args: { id: string },
      context: Context
    ) => {
      return context.dataSources.modelAPI.getModel(args.id);
    },
 
    models: async (
      _: unknown,
      args: {
        first?: number;
        after?: string;
        provider?: string;
        category?: string;
      },
      context: Context
    ) => {
      const limit = args.first ?? 20;
      const models = await context.dataSources.modelAPI.listModels({
        limit: limit + 1,  // hasNextPage 판별용
        cursor: args.after,
        provider: args.provider,
        category: args.category,
      });
 
      const hasNextPage = models.length > limit;
      const edges = models.slice(0, limit).map((model) => ({
        node: model,
        cursor: encodeCursor(model.id),
      }));
 
      return {
        edges,
        pageInfo: {
          hasNextPage,
          hasPreviousPage: !!args.after,
          startCursor: edges[0]?.cursor ?? null,
          endCursor: edges[edges.length - 1]?.cursor ?? null,
        },
        totalCount: await context.dataSources.modelAPI.countModels({
          provider: args.provider,
          category: args.category,
        }),
      };
    },
 
    usageSummary: async (
      _: unknown,
      args: { filter: UsageFilterInput },
      context: Context
    ) => {
      return context.dataSources.usageAPI.getSummary(
        context.userId,
        args.filter
      );
    },
  },
 
  Mutation: {
    createCompletion: async (
      _: unknown,
      args: { input: CompletionInput },
      context: Context
    ) => {
      // 비용 한도 확인
      const withinBudget = await context.dataSources.usageAPI
        .checkBudget(context.userId, args.input.model);
 
      if (!withinBudget) {
        throw new GraphQLError("월간 비용 한도를 초과했습니다", {
          extensions: { code: "BUDGET_EXCEEDED" },
        });
      }
 
      return context.dataSources.inferenceAPI.complete(args.input);
    },
  },
 
  // 필드 리졸버: Model 타입의 pricing 필드
  Model: {
    pricing: async (model: Model, _: unknown, context: Context) => {
      return context.dataSources.pricingAPI.getModelPricing(model.id);
    },
  },
};

# 이 쿼리를 실행하면...
query {
  completions(first: 20) {
    edges {
      node {
        id
        model {          # 각 completion마다 model을 개별 조회
          name            # 1 (목록) + 20 (개별 모델) = 21번 쿼리
          provider
        }
        usage {
          totalTokens
        }
      }
    }
  }
}

import DataLoader from "dataloader";
 
// DataLoader 생성
function createModelLoader(modelAPI: ModelAPI) {
  return new DataLoader<string, Model>(
    async (modelIds: readonly string[]) => {
      // 20개의 개별 요청이 1번의 배치 쿼리로
      const models = await modelAPI.getModelsByIds([...modelIds]);
      
      // DataLoader는 요청 순서대로 결과를 반환해야 함
      const modelMap = new Map(models.map((m) => [m.id, m]));
      return modelIds.map(
        (id) => modelMap.get(id) ?? new Error(`Model ${id} not found`)
      );
    },
    {
      maxBatchSize: 100,
      cache: true,  // 동일 요청 내 캐싱
    }
  );
}
 
// 리졸버에서 DataLoader 사용
const resolvers = {
  Completion: {
    model: async (completion: Completion, _: unknown, context: Context) => {
      // 개별 조회 대신 DataLoader를 통해 배치 처리
      return context.loaders.modelLoader.load(completion.modelId);
    },
  },
};
 
// 컨텍스트 팩토리 (요청마다 새 DataLoader 생성)
function createContext(req: Request): Context {
  return {
    userId: req.userId,
    dataSources: createDataSources(),
    loaders: {
      modelLoader: createModelLoader(modelAPI),
      pricingLoader: createPricingLoader(pricingAPI),
    },
  };
}

# Fragment 정의
fragment ModelBasicInfo on Model {
  id
  name
  provider
  category
  contextWindow
}
 
fragment UsageInfo on TokenUsage {
  promptTokens
  completionTokens
  totalTokens
  estimatedCost
}
 
# Fragment 사용
query CompareModels {
  modelA: model(id: "claude-4") {
    ...ModelBasicInfo
    pricing {
      inputPerMillion
      outputPerMillion
    }
  }
  
  modelB: model(id: "gpt-4o") {
    ...ModelBasicInfo
    pricing {
      inputPerMillion
      outputPerMillion
    }
  }
}

query GetCompletion(
  $id: ID!
  $includeUsage: Boolean!
  $includeCost: Boolean = false
) {
  completion(id: $id) {
    id
    choices {
      message {
        content
      }
    }
    usage @include(if: $includeUsage) {
      promptTokens
      completionTokens
      totalTokens
      estimatedCost @include(if: $includeCost)
    }
    latencyMs
  }
}

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { readFileSync } from "fs";
 
const typeDefs = readFileSync("./schema.graphql", "utf-8");
 
const server = new ApolloServer({
  typeDefs,
  resolvers: [modelResolvers, completionResolvers, usageResolvers],
  plugins: [
    // 쿼리 복잡도 제한
    createComplexityLimitPlugin({ maximumComplexity: 1000 }),
    // 깊이 제한
    createDepthLimitPlugin({ maxDepth: 10 }),
    // 응답 캐싱
    responseCachePlugin(),
  ],
  introspection: process.env.NODE_ENV !== "production",
});
 
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => {
    const userId = await authenticate(req.headers.authorization);
    return createContext(userId);
  },
});
 
console.log(`GraphQL 서버 실행: ${url}`);