TypeScript SDK: 서드파티 인테그레이션 가이드

weave.wrapOpenAI(new OpenAI());

​

Weave 인테그레이션을 TypeScript 프로젝트에서 사용하는 방법

​

어떤 유형의 프로젝트인지 확신이 서지 않는 경우

npx tsx test.ts

"type": "module"

• type이 "module"인 경우, 프로젝트는 ESM을 사용합니다.
• type 필드가 없거나 "commonjs"로 설정된 경우, 프로젝트는 기본적으로 CommonJS를 사용합니다.

​

CommonJS 프로젝트 설정

1. package.json을 생성하거나 업데이트하세요:
   {
     "type": "commonjs"
   }
   
2. CommonJS와 호환되는 설정으로 tsconfig.json을 생성하세요:
   {
     "compilerOptions": {
       "module": "CommonJS",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   
   이 설정은 TypeScript가 CommonJS용으로 컴파일하도록 구성합니다:
   • module: "CommonJS". 모듈을 CommonJS 형식(require 또는 module.exports)으로 컴파일합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module을 참조하세요.
   • target: "es2022"(권장). 최신 Node.js 버전과 호환되는 최신 JavaScript를 내보냅니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Target을 참조하세요.
   • rootDir: ".". tsconfig.json이 포함된 디렉터리를 입력 파일의 루트로 처리합니다. TypeScript는 이 옵션을 outDir과 함께 사용하여 출력에서 소스 폴더 레이아웃을 미러링합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Root Dir을 참조하세요.
   • outDir: "dist". 내보낸 JavaScript와 기타 컴파일러 출력을 dist 폴더에 씁니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Out Dir을 참조하세요.
3. Weave와 기타 필수 라이브러리를 설치하세요:
   npm install weave
   
4. TypeScript 파일을 컴파일하세요. 예시 파일 test.ts의 경우:
   npx tsc
   
   이 명령은 파일을 dist/test.js로 컴파일합니다.
5. 컴파일된 파일을 Node.js로 실행하세요:
   node dist/test.js
   

​

ESM 프로젝트 설정

1. package.json을 생성하거나 업데이트하세요.
   {
     "type": "module"
   }
   
2. Node와 호환되는 ESM 설정으로 tsconfig.json을 생성하세요.
   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   
   이 설정을 사용하면 TypeScript가 최신 Node.js ESM에 맞게 컴파일합니다.
   • module: "nodenext". Node.js ESM 시맨틱을 사용해 모듈을 컴파일합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module을 참조하세요.
   • moduleResolution: "nodenext". 모듈 해석이 Node.js ESM 규칙을 따르도록 합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Module Resolution을 참조하세요.
   • target: "es2022" (권장). 최신 Node.js 버전과 호환되는 최신 JavaScript를 출력합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Target을 참조하세요.
   • rootDir: ".". tsconfig.json이 있는 디렉터리를 입력 파일의 루트로 취급합니다. TypeScript는 이 옵션을 outDir과 함께 사용해 소스 폴더 구조를 출력에 그대로 반영합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Root Dir을 참조하세요.
   • outDir: "dist". 생성된 JavaScript 및 기타 컴파일러 출력을 dist 폴더에 기록합니다. 이 컴파일러 옵션에 대한 자세한 내용은 TypeScript - Out Dir을 참조하세요.
3. Weave와 필요한 기타 라이브러리를 설치하세요.
   npm install weave
   
4. TypeScript 파일을 컴파일하세요. 예시 파일 test.ts의 경우:
   npx tsc
   
   이 명령은 파일을 dist/test.js로 컴파일합니다.
5. Weave 계측을 미리 로드하면서 Node.js로 컴파일된 파일을 실행하세요.
   node --import=weave/instrument dist/test.js
   

​

고급 사용법 및 문제 해결

​

NODE_OPTIONS 사용 (ESM 전용)

export NODE_OPTIONS="--import=weave/instrument"

​

번들러 호환성

1. 번들러 설정에서 LLM 라이브러리를 external로 지정하세요. 그러면 번들러가 해당 라이브러리를 번들링하지 않으므로 Weave가 런타임에 올바르게 패치할 수 있습니다. 다음 예시는 next.config.js 설정에서 openai 패키지를 external로 지정해 번들러가 이를 번들링하지 않도록 하는 방법을 보여 줍니다. 모듈이 런타임에 로드되므로 Weave가 자동으로 패치하고 추적할 수 있습니다. Next.js 같은 프레임워크에서 자동 계측을 사용하려면 이 설정을 적용하세요.
   externals: {
   'openai': 'commonjs openai'
   }
   
2. 그래도 패치에 실패하면 수동 계측을 사용하세요.

​

수동 패치 (대체 옵션)

import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());