全部文档
当前文档
最近更新时间：2026-11-05 15:15:23
/**
* 写入向量（同 key 覆盖）
*
* <p>单批最多 500 条，QPS ≤ 5（调用方控速）。{@code metadata} 为可筛选元数据，值可为任意 JSON value。</p>
*/
public void putVectors() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
try {
List<InputVector> vectors = new ArrayList<>();
Map<String, Object> meta1 = new HashMap<>();
meta1.put("category", "faq");
meta1.put("score", 0.9);
InputVector v1 = new InputVector("doc-001", new VectorData(new float[]{1.0f, 2.0f, 3.0f}));
v1.setMetadata(meta1);
vectors.add(v1);
vectors.add(new InputVector("doc-002", new VectorData(new float[]{4.0f, 5.0f, 6.0f})));
Ks3Result result = client.putVectors(
new PutVectorsRequest(bucketName, indexName, vectors));
System.out.println("写入成功，requestId=" + result.getRequestId());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
/**
* 获取向量（按 key 批量读，单次最多 100 条）
*
* <p>{@code returnData}/{@code returnMetadata} 不传则不出现该键，由服务端默认。</p>
*/
public void getVectors() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
try {
GetVectorsResult result = client.getVectors(
new GetVectorsRequest(bucketName, indexName,
Arrays.asList("doc-001", "doc-002"))
.withReturnData(true)
.withReturnMetadata(true));
List<OutputVector> vectors = result.getVectors();
if (vectors != null) {
for (OutputVector v : vectors) {
System.out.println("key=" + v.getKey() + ", metadata=" + v.getMetadata());
}
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
/**
* 列举索引内向量——串行分页
*
* <p>单次最多 1000 条，{@code nextToken} 为空表示已到最后一页。</p>
*/
public void listVectorsByPage() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
try {
String nextToken = null;
int total = 0;
do {
ListVectorsResult result = client.listVectors(
new ListVectorsRequest(bucketName, indexName)
.withMaxResults(100)
.withNextToken(nextToken)
.withReturnMetadata(true));
List<OutputVector> vectors = result.getVectors();
if (vectors != null) {
total += vectors.size();
for (OutputVector v : vectors) {
System.out.println(" key=" + v.getKey());
}
}
nextToken = result.getNextToken();
} while (nextToken != null && !nextToken.isEmpty());
System.out.println("列举完成，共 " + total + " 条");
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
/**
* 列举索引内向量——并行分段（segmentIndex）
*
* <p>通过 {@code segmentCount}+{@code segmentIndex} 将索引数据划分为 N 段，
* 多线程/多节点并行拉取各段，{@code 1 ≤ segmentIndex <= segmentCount} (1-based）。</p>
*/
public void listVectorsBySegment() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
int segmentCount = 4;
try {
for (int segmentIndex = 1; segmentIndex <= segmentCount; segmentIndex++) {
// 实际可改为多线程并行，这里串行演示分段参数用法
ListVectorsResult result = client.listVectors(
new ListVectorsRequest(bucketName, indexName)
.withMaxResults(100)
.withSegmentCount(segmentCount)
.withSegmentIndex(segmentIndex));
List<OutputVector> vectors = result.getVectors();
System.out.println("段 " + segmentIndex + ": "
+ (vectors == null ? 0 : vectors.size()) + " 条");
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
/**
* 向量相似性检索（QueryVectors）
*
* <p>{@code topK} 可选（传则 1-100），{@code filter} 为元数据预过滤（任意 JSON value，
* 支持操作符）。结果含 {@code distance}（与查询向量的距离）。</p>
*/
public void queryVectors() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
try {
// 过滤条件：category == "faq"，任意 JSON value，用 Map 承装
Map<String, Object> filter = new HashMap<>();
Map<String, Object> eq = new HashMap<>();
eq.put("category", "faq");
filter.put("eq", eq);
QueryVectorsResult result = client.queryVectors(
new QueryVectorsRequest(bucketName, indexName,
new VectorData(new float[]{1.0f, 2.0f, 3.0f}))
.withTopK(5)
.withFilter(filter)
.withReturnData(true)
.withReturnMetadata(true)
.withReturnDistance(true));
List<OutputVector> vectors = result.getVectors();
if (vectors != null) {
for (OutputVector v : vectors) {
System.out.println("key=" + v.getKey()
+ ", distance=" + v.getDistance()
+ ", metadata=" + v.getMetadata());
}
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
/**
* 删除向量
*/
public void deleteVectors() {
Ks3VectorsClient client = initVectorsClient();
String bucketName = "my-vector-bucket";
String indexName = "my-index";
try {
Ks3Result result = client.deleteVectors(
new DeleteVectorsRequest(bucketName, indexName,
Arrays.asList("doc-001", "doc-002")));
System.out.println("删除成功，requestId=" + result.getRequestId());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException: " + e.getErrorMessage()
+ ", status=" + e.getStatusCode() + ", requestId=" + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException: " + e.getMessage());
} finally {
client.shutdown();
}
}
纯净模式