Knowledge API는 구조화된 지식을 관리하기 위한 인터페이스입니다.
const client = new NdxClient({
apiKey: process.env.NEURADEX_API_KEY,
projectId: 'your-project-id',
});
// Knowledge API 접근
client.knowledge.search('쿼리');
client.knowledge.get('id');
client.knowledge.create({ ... });
메서드 목록
| 메서드 | 설명 |
|---|
search(query, options?) | 시맨틱 검색 |
get(id) | 상세 조회 (전체 콘텐츠 + 관련 지식) |
list() | 목록 조회 |
create(input) | 생성 |
bulkCreate(items) | 일괄 생성 |
update(id, input) | 수정 |
delete(id) | 삭제 |
export() | 내보내기 |
getHistory(id, options?) | 변경 이력 조회 |
getEdges(id, options?) | 관련 엣지 조회 |
search()
시맨틱 검색을 실행합니다. 자연어 쿼리에 대해 관련성 높은 지식을 반환합니다.
검색 결과에는 전체 콘텐츠가 포함되지 않습니다. 콘텐츠가 필요하면 get()을 사용하세요.
파라미터
반환값
interface SearchResult {
id: string;
title: string;
tags: string[];
score: number; // 관련성 점수 (0-1)
summary: string | null; // LLM 생성 요약
contentTokens: number | null;
createdAt: string | null;
indexedAt: string | null;
}
사용 예
// 기본 검색
const results = await client.knowledge.search('인증 방식');
for (const result of results) {
console.log(`${result.title} (점수: ${result.score.toFixed(2)})`);
}
// 결과 수 지정
const topResults = await client.knowledge.search('반품', { limit: 5 });
get()
지식의 상세 정보를 가져옵니다. 전체 콘텐츠와 관련 지식이 포함됩니다.
파라미터
반환값
interface KnowledgeViewResponse {
id: string;
title: string;
content: string;
tags: string[];
summary: string | null;
contentTokens: number | null;
createdAt: string;
updatedAt: string;
connectedKnowledge: ConnectedKnowledge[];
}
interface ConnectedKnowledge {
id: string;
title: string;
relationType: string;
weight: number;
isActive: boolean;
validFrom: string;
validUntil: string | null;
}
사용 예
const detail = await client.knowledge.get('knowledge-id');
console.log(detail.title);
console.log(detail.content);
// 관련 지식 확인
for (const connected of detail.connectedKnowledge) {
console.log(`관련: ${connected.title} (${connected.relationType})`);
}
list()
프로젝트 내 모든 지식을 가져옵니다.
반환값
interface Knowledge {
id: string;
title: string;
content: string;
tags: string[];
createdAt: string;
updatedAt: string;
}
사용 예
const allKnowledge = await client.knowledge.list();
console.log(`지식 수: ${allKnowledge.length}`);
create()
새로운 지식을 생성합니다.
파라미터
사용 예
const knowledge = await client.knowledge.create({
title: 'React Hooks 입문',
content: `
React Hooks는 함수 컴포넌트에서 상태와 라이프사이클을 다루는 기능입니다.
## useState
컴포넌트 상태를 관리합니다.
## useEffect
부수 효과(API 호출, DOM 조작 등)를 처리합니다.
`,
tags: ['React', '프론트엔드', 'JavaScript'],
});
console.log(`생성 완료: ${knowledge.id}`);
bulkCreate()
여러 지식을 일괄 생성합니다.
파라미터
사용 예
const items = await client.knowledge.bulkCreate([
{
title: 'TypeScript 기초',
content: 'TypeScript는 정적 타입을 제공하는 JavaScript의 상위 집합입니다.',
tags: ['TypeScript', '프로그래밍'],
},
{
title: 'Node.js 기초',
content: 'Node.js는 서버 사이드 JavaScript 실행 환경입니다.',
tags: ['Node.js', '백엔드'],
},
]);
console.log(`${items.length}개 생성 완료`);
update()
기존 지식을 수정합니다.
파라미터
사용 예
// 제목만 수정
const updated = await client.knowledge.update('knowledge-id', {
title: '새로운 제목',
});
// 내용만 수정
const updated = await client.knowledge.update('knowledge-id', {
content: '수정된 내용',
});
// 둘 다 수정
const updated = await client.knowledge.update('knowledge-id', {
title: '새로운 제목',
content: '수정된 내용',
});
delete()
지식을 삭제합니다.
파라미터
사용 예
await client.knowledge.delete('knowledge-id');
console.log('삭제 완료');
export()
모든 지식을 내보내기 형식으로 가져옵니다.
반환값
Array<{ title: string; content: string }>
사용 예
const exported = await client.knowledge.export();
// JSON으로 저장
import fs from 'fs';
fs.writeFileSync('knowledge-backup.json', JSON.stringify(exported, null, 2));
getHistory()
지식의 변경 이력을 가져옵니다. 생성·수정·삭제 이벤트를 시간순으로 반환합니다.
파라미터
사용 예
const history = await client.knowledge.getHistory('knowledge-id');
for (const episode of history) {
console.log(`${episode.episodeType}: ${episode.content}`);
console.log(` 이유: ${episode.changeReason}`);
console.log(` 실행자: ${episode.actorName}`);
console.log(` 일시: ${episode.occurredAt}`);
}
getEdges()
지식에 관련된 엣지(관계)를 가져옵니다.
파라미터
사용 예
// 활성 엣지만
const activeEdges = await client.knowledge.getEdges('knowledge-id');
// 이력도 포함
const allEdges = await client.knowledge.getEdges('knowledge-id', {
includeHistory: true,
});
for (const edge of allEdges) {
console.log(`${edge.title} (${edge.relationType})`);
console.log(` 활성: ${edge.isActive}`);
console.log(` 유효 기간: ${edge.validFrom} - ${edge.validUntil ?? '현재'}`);
}
다음 단계
